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SLIP: A Symmetric List Processing Language in PL-I 

William A. Leaf 
Carnegie -Mellon University 



This description of SLIP is written for the reader who has at least 
a basic knowledge of PL-I terminology, conventions, and programming. 

Since this SLIP (and PL-l) are written for IBM-360 computers, the 
machine -oriented details in the following pages are 360 details. As much 
detail as possible has been provided ^o that the interested reader can 
understand the physical representation of SLIP cells and lists. The user 
interested only in the features of the language can skip such hardware 
information without loss of understanding. 

The version of SLIP described here is written for the OS version of 
PL-I, specifically version 4, release If of the PL-l(F) compiler. Only 
minor changes in the routines are necessary to adapt them to other releases 
or versions of the (F) compiler. 
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SLIP: A Symmetric List Processing Language in PL-I 

William A. Leaf* 

Carnegie -Me lion University 

General Features of SLIP 

SLIP is a list processing system originally developed by Joseph 
Weizenbaum (196^). It is designed to be added to a higher order language, 
PL-I in this version, so that the user has available to him, in addition to 
the host algebraic language, list processing powers similar to those of 
languages like IPL-V, LISP, or FLPL. 

The primary value of such a system is its data handling power. Through 
SLIP, one can set up lists of data, scan those lists, alter them, and read 
or wi’ite them \ ia external devices with minimal concern for space allotment, 
data types, or data structure organization. It is possible, for example, to 
write general programs which create and manipulaoe list structures whose 
shape, size, and contents are completely defined only during execution, by 
the shape, size, and contents of the data. 

SLIP exists as a set of library subroutines which do the actual manipu- 
lations. Thus the user simply writes a normal PL-I program in which some 
statements refer to SLIP functions. The user has access to all the normal 
facilities of PL-I and, in addition, has the power to create and manipulate 
data lists. 

Weizenbaum orginally wrote SLIP to be imbedded in FORTRAN; since then, 
it has been adapted to be used with other algebraic languages (e.g., MAD; 
see Johnson, Rosin, & Leaf, 1967) and has been adapted at least once to 
PL-I (Johnson, 1968). 

*This work was done while the author was a Visiting Research Psychologist 
at Educational Testing Service. 
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The present version of SLIP differs from the earlier versions in many 
respects. The major reason for this is the large difference between 
FORTRAN and PL-I. The latter language has a much wider variety of data 
types than the former, and it seemed important to mirror this flexibility 
in SLIP. 

Thus the form of data storage has been changed slightly to fit with 
PL-I conventions. Many of L'he functions in SLIP now do slightly different 
things, in different ways, than they did in the earlier versions. And the 
names of the functions have sometimes been changed, primarily to improve 
the mnemonics but also to take advantage of the fact that PL-I allows 
7-character names. 

SLIP's overall powers and purposes have not been changed, however. 

The basic features of the language can be briefly summarized under four 
headings: list creation and manipulation, list scanning, description lists, 

and list input -output . 

List creation and manipulatio n. Lists may contain any number of data 
cells and sublists (which have all the flexibility of main lists). Lists 
may be created (via the function LIST), copied (COPYLST), or erased 
(ERASL3T). New data ma^ be added to a list (NEWTOP, NEWBOT) or they may 
replace old data (SUBTOP, SUBBOT, REPLACE). Old data may be retrieved 
(TOP, BOT, DATUM) or removed from lists (POPTOP, POPBOT, REMOVE). The 
entire contents of a list may be moved to another list (MOVEL, MOVER) or 
erased (EMTYIBT). 

List scanning . The functions described above are best for manipulating 
data at the top or bottom of a list. By means of SLIP's reader facility. 
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however, one can scan through a list or its sublists for data, then remove, 
replace, or retrieve the data as desired. Readers are pointers which may 
be moved up or down a list (via the advanc e functions, ADV3TR, AI7STL, 

ADVLNR, and ADVLNL) to find any kind of datum or a particular kind of 
datum. 

A particularly useful function, SEARCH, will scan a l.'st's data for 
a particular datum. 

Description lists . It is often useful to attach to a list a set of 
descriptors which identify the nature of the list (its data types or its 
importance to the program). Each list may have a description list which 
contains such information in Attribute Dimension-Value pairs. Specialized 
functions exist which conveniently manip.ilate such descriptive information. 

For example, NEVJVAL stores the value for a particular attribute, ITSVAL 
retrieves the current value, and NOVAL removes the attribute and its value 
from the description list. 

List input -output . Often the most economical way to create complex 
lists is to prepare them as input for the running program. Two functions, 
READLST and PRNTLST, exist which can read and write lists of any complexity. 
The output from PRNTLST is readable by READLST, so that one can save lists 
from day to day or use one program to create a complex list for another. 

Organization of SLIP Lists 

Lists are made up of a main cell, or header, and any number of data 
cells (see below for a description of the data types which may be stored in 
cells). The cells are linked together linearly and symmetrically. That is, 
the header is linked to the first data cell, the first is linked to the second 
cell, . . . , the next-to-last cell is linked to the last cell, and the 
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last cell is linked to the header. In addition, the header is linked back 
to the last cell and all other cells are linked back to the preceding cell 
on the list. Thus the keyword symmetric : from any point on the list, it 

is possible to use the chain of links to go either forward or backward to 
any other point on the list. (The terminology for locating cells on a 
list relative to other cells on the list can be confusing. In normal linear 
lists, data cells are either above or below each other, and the header cell 
is the top of the list. These terms are still used in SLIP, but since lists 
are symmetric, a conventional meaning for "above" and "below" must be agreed 
upon. Each cell has two links; conventionally, the one called "IIKR" ( link 

right ) points forward to the cell below the current cell. The link left 

("LNKL") points upward or backward to the preceding cell. Exceptions occur 

around the header, but it is traditionally regarded as the top of the list, 

and the cell to the "left" of the header is regarded as the bot'com of the 
list. ) 

Data cells may contain data such as numbers or bit or character strings. 
They may also contain pointers to other lists. Thus any list may have any 
number of sublists, which in turn may have sublists of their own, etc. A 
list may be its own sublist. Thus it is possible to create extremely com- 
plex list structures. 

A list may also have a description list . In IPL-V, description lists 
were usually seen as containing descriptive information about the nature 
of the main list, information completely separate from its contents. In 
SLIP, one may use the description lists for the same purposes; there are 
specialized subroutines designed to conveniently create and scan such lists. 
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Or one can use a description list Per any purpose desired; practically, 
description lists have all the flexibility of organization and use as 
other lists, including the ability to have description lists. 

SLIP Cells 

Figure 1 gives the schematic form for any SLIP cell. Because PL-I 
allows data of different physical lengths, the actual length of a cell is 
determined by its datum. Each ce-'. is made up of a twe-word "links" portion 
followed by the datum. 



SLIP field 


ID 


LNKL 

J | 


MARK 


LNKR 

_ i | 


datum 


Byte 


0 


1 1 

12 5 


k 


1 1 

567 


8 ... 4n-l 



Figure 1. Storage xepresentation of a typical SLIP cell. 

The first byte of the cell (which always oegins on a fullword boundary) 
contains the ID which identifies the type of datum contained in the cell; 
currently, ID values of 1 to 15 are meaningful (see below). The rest of the 
first word (bytes 1-5) is the lirk left which points to the next, higher cell 
on the same l'st. The second word begins with a 1-byte MARK portion. It is 
unused by SLIP, but may be used by the programmer to identify particula- 
cells--for example, during a searching or scanning operation. The MARK is 
initially set to 0; if may be given any value from 0 to 255* Bytes 5-7 of 
the second word (LNKR) contain the link to the next lower cell on the list. 
Both LNKR and LNKL are machine addresses corresponding to PL-I pointer 



variables. 
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ID 


DATUM Type & 


1 


fixed binary ( 15 , 0 ) 


(default! 


1 


2 


fixed binary ( 31 , 0 ) 


(maximum) 


1 


3 


float binary ( 2 l) 


(default ! 


1 


1 + 


float binary (53) 


(maximum) 


1 


5 


fixed decimal ( 5 , 0 ) 


(default) 


» 


6 


fixed decimal (l 5 , 0 ) 


(maximum) 


1 


7 


float decimal ( 6 ) 


(default! 


1 


8 


float decimal (l 6 ) 


(maximum) 


1 


9 


character string (< 256 ) 






10 


bit string (< 20487 






11 


name of sublist (pointer variable) 




12 


header of list ( 8 -byte datum) containing a 




description list name (pointer variable) 




and a reference counter 


'(binary integer) 


13 


reader cell 



Figure 2. Allowable SLIP data types and their corresponding 
SLIP IDs. While only codes 1-11 are strictly data, codes 12 and J3 
are included in this table for completeness. 

a 

The parenthesized numbers represent the length of the datum 
and, if present, the scale factor. 

Header cells (ID - 12) . The datum portion of a header cell is made up 
of two words. The first word contains a pointer to the list's description 
list, if any. The second word is a binary integer whose value is the list's 
reference counter . The reference counter tallies the number of times the 
list has been mentioned on other lists as a sublist or a description list. 

The tally is extremely important in telling SLIP if it is all right to erase 
a list or if the list cannot be erased because it is referenced by other 
valid lists. (See Space Managing below for more details.) 

Reader cells (ID = JJ). Reader cells are special application cells used 
by the reader mechanisms for scanning list structures. They cannot be used 
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Llwmsf’l/f’O ns lint items . ([W« The Header Facility be Low fer a e'>tnpifi..- 

description. ) 

Data cells (ID - 1 to ll) . PL-I has a very wide range of data type?:-- 
binary and decimal integer and floating point numbers, complex numbers, 
puinter and offset variables, bit and character strings, and pound sterling 
values, for example --but a certain inflexibility in mixing data types. The 
11 data types actually allowed in SLIP cells represent a compromise intended 
to give the user the freedom to use as many meaningfully different data 
typos as possible. Some data types are omitted completely, such as offset 
variables and complex variables; they are the ones which seem to have the 
least value to SLIP programmers. 

Binary fixed point numbers, in version 4 of PL-I, are all stored in 
full computer words regardless of precision. SLIP allows the default 
precision (15,0; ID = l) and the maximum precision (51,0; ID - ?). (Pre- 
cision figures in PL-I definitions are in terms of the base used. Thus a 
fixed binary number of default precision allows 15 binary places; this is 
approximately equivalent to the default precision of fixed decimal numbers, 
which is 5 decimal digits.) 

Fixed decimal numbers in PL-I are stored internally as decimal digits 
plus a sign. Such numbers may vary in length from 1 byte (precision - l) 
to 2 words (precision = 15). SLIP allows the default precision (5,0; 

ID = 5) and the maximum (15,0; ID = 6). 

Floating point numbers, either binary or decimal, are all stored in 
the 56c as floating hexadecimal numbers of either 1 or 2 words in length. 
Because PL-I distinguishes between float binary and float decimal, both 
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are allowed separately in SLIP. The default precisions of float binary 
(21; ID - 5) and float • ecimal (6; ID = 7) are equivalent; each is 1 word 
long. Also allowed are the maximum precisions for float binary (53; ID = 
4) and float decimal (l6; ID = 8); each is 2 words long. 

Strings in PL-I consist of two parts: a two-word Dope Vector and the 

string itself. The Dope Vector contains the address of the string in the 
first word and the actual and maximum possible lengths of the string in 
the second word (the two lengths may be different in the case of variable 
length strings). Character strings are stored with 1 character per byte; 
bit strings are stored with 8 bits per byte. In a SLIP data cell, a 
string is stored with the Dope Vector in the first 2 datum words and the 
string itself in the following words. All strings are stored as if they 
are of variable length; the maximum length for any string is the smallest 
number of full words needed to store the actual string. 

In data cells, strings may be up to 256 characters in length (ID = 9) 
or 2048 bits in length (ID = 10 ). 

Sublist names (ID = ll) are actually pointer variables; these are 1 
word long. For a pointer variable to be the name of r. sublist, its value 
must be the address of the sublist's header. 

SLIP cells are all made up of s round number of computer words, even 
when the datum does not require the entire space (as for ID = 5 and for 
many cases with ID = 9 or 10 ). The minimum number of words in a cell is 
3 (ID = 1, 2, 5, 5> 1 > and ll); the maximum possible length is 68 words 
(ID = 9 and 10) although the exact length of string cells is determined 
by the length of the strings. 
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The List of Availt.'jle Space (AVSL) 

SLIP cells are created from a lir,t of available space which is set up 
by the programmer outside his own program area by calling the function 
I NIT AS . 

Originally, the list contains 4096 bytes of core. It can be increased 
by 1024 -byte increments, whenever ohe cur-rent space is completely used, by 
automatic calls for more space, up to the limits of the machine storage 
allocated to the user. After first calling INITAS, the user need concern 
himself no more with available space. To him, it appears that all the rest 
of his job partition space is available at once. The job is terminated if 
a request is made for more space when none is available or can be found. 

At that time, one of two messages is printed out: 

**** initas COULD NOT ALLOCATE ANY SPACE FOR SLIP LIST STRUCTURE STORAGE. 
**** GO. REG ION WAS TOO SMALL. PROGRAM TERMINATED. 

if the program took up so much of the user's space that INITAS could not 
even allocate the initial partition, or 

**** NO MORE SPACE COULD PE OBTAINED ATTER xxxxx BYTES HAD BEEN ALLOCATED 

TO SLIP. 

**** yyyyy bytes were still free but in segments too small to be used. 

**** PROGRAM terminated. 

if INITAS had been able to successfully ^ind space at least once, xxxxx and 
yyyyy are numiers; yyyyy can be greater than zero and allocation can still 
fail if the bytes are in separate pieces each too small tq hold the new 
cell. (If yyyyy = 0, that comment line does not appear.) 

AVSL consists of one or more segments of core, in full -word denomina- 
tions aligned on full-word boundaries, linked together. The first word of 
each slot contains the address of the first word of the next slot; the 
second word contains the length of the slot in bytes. (Slots of 4 bytes 
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length have no second word; their short length is indicated by a minus sign 
in the first word.) Slots are ordered ii’om longest to shortest. 

A request for space from AVSL to create a new cell causes the smallest 
slot which is still large enough to hold the cell to be removed from AVSL. 
The bytes necessary for the new cell are taken from that slot, and any 
"leftover" bytes are returned to AVSL, taking their place in order by size. 
Cells to be erased, i.e., returned to AVSL, are put back in the list as 
are leftovers from cell allocations. In returning pieces of storage to 
AVSL, SLIP checks to see whether they are adjacent to slots already on 
AVSL. If so, they are combined into one long slot and returned to AVSL 
in that form. 

Space Managing 

In any list processing system, some provisions must exist for returning 
unused cells to the list of available space so that no bit of space is 
permanently lost. In SLIP, as much as possible of this erasing process is 
handled by the system — both to relieve ohe user of needless space managing 
chores and to guard against the possibility of errors. 

Removing data cells presents no problem, since a data cell does not 
control other storage. Removing header cells, however, which happens 
whenever a list is erased, may v.j.use problems. If, for example, list A 
is a sublist of list B, one must not erase A while B still exists. Erasing 
A would not alter the structure of B, which contains a cell pointing to 
the sublist A, and any subsequent effort to scan B's structure (e.g., using 
reader facilities) would fail when it tried to enter the "sublist" which no 





longer exists. 
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SLIP maneuvers around this diffiei lty by means of each list's refer- 
ence counter. When a list (e.g., A) is created, its reference counter is 
usually 1. If A is made a sublist or the description list of another list, 

A' s reference co’inter is increased by 1. If an attempt is made to erase A, 
via the ERASLST function, the ieference counter of A is decreased by 1. Only 
if the new value of the reference counter is 0 or less is A actually erased. 
In the example, A would not be erased because it is a sublist. 

If a xist is actually erased, all its cells are returned to AVSL. 

In addition, an attempt is made to erase all of the list's sublists and 
its description list: the reference counters of those lists are reduced 

by 1 and any of the lists whose new reference values are 0 or less are 
physically erased. 



Example 1 . 

The following short program illustrates the use of some SLIP facilities 
on a simple problem: dealing 200 blackjack hands from a complete deck. 

Notes : (The numbers refer to statement numbers in DEAL) 

2. NEWBOT is a generic function which in fact has entries for each 
allowable SLIP data type; only the entry for character data is needed in 
this program, so the full declaration for NEWBOT is not used. 

3. LIST is also a generic function. Since only its first entry 
point is needed, only that one is defined. 

4. This initializes available space for SLIP. 

5- The input cards are set to give DECK 52 sublists, each repre- 
senting a card; each sublist contains two elements--the first is the 
character string name of the card, e.g., CLUB. KING, and the second is the 
point value of the card, e.g., 10. To simplify things, aces are assumed 
to count 11. 

6. N is the number of hands to be dealt. 

7* This makes an empty SLIP list which will contain the cards from 
each deal. 

9* Each card, when dealt into HAND, will be marked with an index 
number between 0 and 255 so that the card can't be dealt twice into the 
same hand. 
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11 • RANDEL' s value is the address of a randomly-selected element 
(card) on DECK. 

12. DATUM sets CARD equal to the datum in the cell addressed by 
POINTR* Thus CARD is the name of the sublist with the card name and its 
point value. 

15* Don't put the same card twice into the same hand. 

1 5* CARDSTRING is given the character name of the card being dealt. 
1 6 . The card is actually "dealt" onto HAND. 

19* Iterate until the hand's count is 21 or more. 

21. Print the cards dealt in the complete hand and 

22. print the total point value. 

25" Empty the list in preparation for the next deal. 
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DF.AL: PROC OPTION S ( M A IN ) ; 



STMT LEVEL NEST 

1 

2 1 



3 

a 

5 

6 

7 

8 
8 

10 
1 1 
12 
13 

1 5 

16 

17 

18 
19 
21 
22 

23 

24 

25 



1 

1 

1 

1 

1 

1 

1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 1 
1 



DEAL: PROC OPTIONS (MAIN); 

DCL (DECK, HAND, POINTS, CARD) PTR, »N , I, K, COUNT, ITSCOUNT) 
FIXE D BIN (31), RANDEL RETURNS (PTR), HARK RETURNS (FIXED PI 
(31)), NEWBOT GENERIC ( NEWBOT9 ENTRY (PTR, CHAR(1) VAR)), 
CARDSTRING CHAR (48) VAR, TOP RETURNS (CHAR(48) VAR), 

BOT RETURNS (FIXED BIN (31)), READLST GENERIC (READLSl 
ENTRY (PTR)), PRNTLST GENERIC (PRNTLSl ENTRY (PTR)); 

DCL LIST GENERIC ( LIST 1 ENTRY (PTR)); 

CALL INTTAS; 

CALL READLST (DECK); 

N = 200; 

CALL LIST (HAND); 

DO I = 1 TO N; 

K = MOD (I, 256) ; 

COUNT = 0 ; 

LOOP: POINTR = RANDEL ( DECK ) ; 

CALL DATUM 'POINTR, CARD) ; 

IF N ARK ( CAR D) = K THEN GO TO LOOP; 

CARDSTRING = TOP(CARC); 

CALL NEWBOT (HAND, CARDSTRING); 

ITSCOUNT = BOT (CARD) ; 

COUNT = COUNT ♦ ITSCOUNT; 

IP COUNT < 21 THEN GO TO LOOP; 

CALL PRNTLST (HAND) ; 

PUT DATA (COUNT) ; 

CALL EMTYLST(HAND) ; 

END; 

END DEAL; 



Below is sample output from the program shown above. 



( DIAMOND. ACE HEART. FOUR CLUB.OUEEN > 

COUNT— 25; 

( SPADE. EIGHT SPADE. KING DIAMOND. QUEFN ) 

COUNT® 28; 

( HEART. TWO DI AH ON D. THREE SPADE. JACK CLUB. NINE ) 
COUNT® 24; 

( CLUB. TEN DIAMOND. JACK HEART. TEN ) 

COUNT® 30; 

( CLUB. FIVE HEART. KING SPADE. TEN ) 

COUNT® 25; 

( HEART. FIVE DIAMOND. QUEEN SPADE. POUR HEART. JACK ) 
COUNT® 29; 

( CLUB. SEVEN DI A MOND. Q UEFN HEART. KING ) 

COUNT® 27; 

( HEART. JACK HEART. KING DIAMOND. FIVE ) 

COUNT® 25; 

( DIAMOND. ACE HEART. SIX CLUB. FOUR ) 

COUNT® 21; 

( SPADE. SIX DIAMOND. THREE SPADE. KING CLUB. TEN ) 
COUNT® 29; 

\ ■ 

' H 
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Facilities in SLIP 

The following sections describe the types of things which can be done 
using SLIP. In each section, a general description and its examples are 
followed by a formal description of the functions introduced in the section. 
The index at the end of this paper allows one to easily locate the descrip- 
tion of any particular function. 

In the description for each function, the allowable calling sequences 
are listed; they include the list of possible variables. The names of the 
variables are intended to indicate the data type of the variables. In 
summary form, the 1 ist below shows the exact data type for the dummy 
variables used in the following sections. 

LST, LST1, LST2, ORGL, COPY, C0P2, HOST, DLST; FNTR, POINT, CELL, LINKR, 
LIHKL; KDR, RDR2. These are all pointer variables, (in general, all main 
program variables which name lists or readers or otherwise address SLIP 
cells should be pointer variables.) LST through DLST are list names (i.e., 
they contain the addresses of list headers). PNTR through LINKL are cell 
addresses; in some cases, the cells may be headers which would make the 
variable a list name. RDR and RDR2 have the addresses of reader cells, 
which makes them reader names. 

DATM, DAT1, DAT2, OLDDAT, ATTR, VALU, OLDVAL, NUVAL. These are allow- 
able SLIP data, which may correspond to any of the data types with ID values 
between 1 and 11 in Figure 2. 

DATID, ATID, VALID, LVL, INT, LNGTH, I, J. These are all binary 
integers . The first three are used as ID values and, in particular, should 
only have values between 1 and 11. 
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STRING may be any bit or character string. 

FILENAM is the name of a stream input or stream output file. 

X, Y, DX, and DY are floating point numbers. X and Y are one word 
long; DX and DY are two words long. 

VAR may be any variable which does not have a Dope Vector (i.e., any 
nonstring, nonarray variable). 

CODE is a binary integer with values between 0 and 9* 

Initializing Available Space 

In order to use SLIP functions, one must first set up the list of 
available space so that SLIP cells may be created and erased. This is 
accomplished by the statement "CALL INITAS;". In the program, this step 
must be executed only once and before any other SLIP functions are called. 
It is often easiest to make this the first executable statement in the 
program. (See Appendix A for a convenient way of insuring this.) 

CALL INITAS; or CALL INITAS (iNT); 

This function makes available to SLIP all the unused machine storage 
in the programmer's region. It also initializes all new space to 0 except 
for the link words necessary to chain the segments of AVSL together. 

INITAS sets in motion the housekeeping aspects of SLIP which will generate 
new cells when required and erase old cells when no longer needed. 

The argument INT, if included, is relevant to SLIP's error detection 
procedures (see Appendix B). SLIP normally notes errors during execution 
and continues processing; to keep from running indefinitely, SLIP tallies 
those errors* By default, the program is terminated after 5 0 such errors; 
the argument INT, if included, serves as the new cutoff criterion. 

, : i . 
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Creating and Modifying Lists 

The functions to be described in this section perform the basic func- 
tions of creating lists, adding, subtracting, and replacing elements, re- 
trieving data, reshaping lists, and erasing lists. 



Example 2. 

Certain models of memory taken from psychology utilize short-term 
memory banks; these may be represented by SLIP list structures. Assume for 
the following segments of program that MEMORY is a list whose elements are 
the items cur antly held in short-term memory (e.g., CVC trigram pairs in a 
paired associates learning task). The code shown will move new pairs" into 
memory and remove "forgotten" pairs - according to three different schemes. 

A. Assume an infinite memory in which no old pairs are forgotten. 

• • • 

CALL NEWTO P (MEMO RY, CVCONE !! ' = ' || CVCTWO); 

• • • 

Or, if one wishes to place the new pair at a random position on the list, 

• • • 

N = NUMBEL (MEMORY) + 1; 

IF IRAND(N) = 0 THEN PLACE = MEMORY; 

ELSE PLACE = RANDEL (MEMORY ) ; /* * PLACE is a pointer variable */ 

CALL NEWTOP(PLACE, CVCONE || || CVCTWO); 

• • • 

B. If memory is of fixed length and the pair to be replaced by the 
new pair is the oldest one, the following code will add new pairs to the 
top of MEMORY and, if memory is full, remove the old pairs from the bottom. 

• • • 

CALL NEWTO P (MEMO RY, CVCONE || ' = ' || CVCTWO); 

IF NUMBEL (MEMORY) > N THEN CALL POPBOT (MEMORY); 

• • • 
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C. If the memory is of fixed maximum length, the following code will 
replace randomly selected old pairs with new pairs when the memory is full. 

• • • 

IF NUMBEL(MEMORY) < N THEN CALL NEWTOP(MEMORY,CVCONE || * = * || CVCTWO); 

ELSE CALL REPLACE (RANDEL (MEMORY ), CVCONE il ' = ' || CVCTWO) ; 

• • • . 

In examples 2B and 2C it is possible to retrieve the value of the 
erased pair by using FOPBOT or REPLACE as functions; e.g., 

OLDPAIR = FOPBOT (MEMORY ) ; 

if OLDPAIR is a character string variable and one uses a slightly unorthodox 
declaration for FOPBOT or REPLACE, e.g., 

DCL POPBOT RETURNS (CHAR(20) VAR); 

CALL LIST(LST) ; or LST2 = LIST(LST); or LST = LIST (9); 

LIST creates an empty list and in each of the statements above assigns 
to LST the name of the new list (i.e., places the address of its header 
cell in 1ST). In the second version, LST2 is also given the name of the 
list. 

If the argument is a pointer variable, the reference counter of the 
list is set to 1. In that case, the list can be erased only by an explicit 
call to ERASLST . If the argument is (the decimal constant) 9, the reference 
counter is set to 0. The list may be automatically erased if, for example, 
it is the sublist of another list which is erased. 

CALL COPYLST (ORGL, COPY); or C0P2 = C0FYLST(0RGL, COPY); 
or COPY = COPYLST (ORGL); 

ORGL, COPY, and C0P2 are pointer variables. 
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COPYLST creates an exact copy of the entire list structure named ORGL 
and assigns the name of the copy to COPY and, if appropriate, C0P2. If 
COPY is already the name of a list, the contents of ORGL are placed below 
the current contents of COFY* 

COFYLST makes copies of all sublists and description lists in the list 
structure of ORGL; thus the original and its copy are physically distinct. 
The topography of the original is repeated in the copy; if, for example, 
the original references the same sublist twice, the copy r< ■**«■' r-"-'es a 
single copy of the sublist twice. 

CALL EMTYLST ( LST ) ; or LST2 = EMTYLST(LST) ; 

LST is made into an empty list; its data cells are returned to AVSL, 
including sublists where appropriate. The description list of LST, if 
there is one, is not erased. LST2 is given the name of the now empty list 
(i.e., is made equa.1 to LST). 

CALL ERASLST (LST ) ; or LVL = ERASLST(LST) ; 

ERASLST first decrements the reference counter of LST by 1. If the 
counter's new value is greater than 0, indicating that LST is still the 
sublist or description list of some existing list, nothing further is 
done . 

All levels of LST are removed--top level, its description list, any 
sublists, their description lists, their sublists, etc. --subject to the 
same restrictions that apply to the main list: lists with a new refer- 

ence level of more than 0 are retained. 

If called as a function, ERASLST returns a binary integer whose value 
is the new value of LST's reference counter. If LVL = 0, the list has been 
erased. 
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CALL NEWTOP(LST, DATM); or PNTR NEWTOP(LST, DATM); 

CALL NEWBOT(LST, DATM); or PNTR = NEWBOT(LST, DATM); 

NEWTOP (NEWBOT) creates a new SLIP cell containing DATM and places 
that cell at the top (bottom) of the list named LST. All other cells of 
the list are unchanged; the effect is of putting a new link in a chain 
without breaking or rearranging any other links. 

DATM may be any of the 11 data types which may be stored on lists; 
NEWTOP and NEWBOT are generic functions with separate entries for each 
data type (see Appendix c). 

PNTR is a pointer variable which, if used, is given the address of 
the newly created cell. 

The first argument "LST" for either function may point at a cell on 
a list rather than name the list; in that case, the new cell is placed to 
the right of the addressed cell (for NEWTOP; to the left for NEWBOT). 

CALL SUBTOP(LST, DATM [, ID] [, OLDDAT]); 

CALL SUBBOT (LST, DATM [, ID] [, OLDDAT]); 

CALL REPLACE (PNTR, DATM [, ID] [, OLDDAT]); 

All three functions remove a data cell from a list and replace it with 
a new cell containing DATM. (DATM must be an allowable SLIP data type; LST 
and PNTR are pointer variables; and ID, if present, is a binary integer 
whose value is the SLIP ID number corresponding to the data type of DATM* 

If ID is omitted, it is assumed that DATM is the same type as the datum 
of the erased cell.) 

OLDDAT, if present, is given the value of the datum of the erased cell. 
OLDDAT must be of the appropriate type; no conversion is made. 

If LST names a list, SUBTOP replaces tne top data cell on the list and 
SUBBOT replaces the bottom cell. As in the case of NEWTOP, LST may be the 
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address of any list cell: the only restriction is that the removed cell 

may not be the list's header. 

REPLACE replaces the cell addressed by PNTR; that cell may not be a 
list header. 

Programming note . In programs in which SUBTOP, SUBBOT, or REPLACE is 
used to replace a single data type, it may be declared and used as a func- 
tion which returns that datum type. For example, if only character string 
data are replaced, one can say DCL SUBTOP ENTRY ( PTR, , FIXED BIN (3l)) 
RETURNS (CHAR (20)VAR); and then use statements like OLDSTR = SUBTOP (LST, 
NEWSTR, 9). 

CALL T0P(LST, DATM) ; 

CALL BOT (LST, DATM); 

CALL DATUM ( PNTR, DATM); 

LST is usually the name of a list, although it may be the address of 
any list cell. HJTR is the address of any cell except a list header. DATM 
is set to the value of the datum in the cell to the right of that addressed 
by LST (for TOP) or to the left of that addressed by I£T (for BOT), or in 
the cell addressed by HTR (for DATUM). 

Programming note . In programs in which TOP, BOT, or DATUM is used 
only for a single data type, it may be declared and used as a function 
which returns that datum type. Two instances of this are shown in Example 
1 above . 

CALL P0FT0P(I£T[, DATM]); 

CALL P0PB0T(LST[, DATM]);. 

CALL REMOVE (PNTR[, DATM]); 

These three functions work like TOP, BOT, and DATUM and in addition 
erase the cell in question. Because one may wish to remove a cell without 



7Z 



- 21 - 



being given its datum, the DATM argument may be omitted. If DATM is 
present, it must be of the same data type as the datum in the cell. 

When the cell is removed from a list, the remainder of the list is 
linked around the gap. The cell to be removed may not be a list header. 

Programming note . If POPTOP, POPBOT, or REMOVE is being used only 
to return a single datum type, it may be declared to return that datum 
type and used in assignment statements, e.g., ZORCH = POPTOP(LST); • 

CALL MOVER ( 1ST 1, LST2 ) ; 

CALL M0VEL(LST1, LST2 ) ; 

MOVER and MOVEL move the entire contents of LST2 onto LST1. MOVER 
places the transferred cells at the bottom of any prior contents of LST1; 
MOVEL puts the moved cells at the top of LST1, above its prior contents. 

If LST2 is the address of a cell on a list rather than a list name, 
then the cells moved are the ones between the addressed cell and the bottom 
(for MOVER) or the top (for MOVEL) of the list containing the cell. 

Input/Output Facilities for Lists 

The functions described in the preceding section are useful for making 
delicate and relatively small-scale modifications to lists. For creating 
large or complicated lists, it is much more efficient to read the list from 
a stream input file by means of READU3T. 

Also discussed in this section are the specialized functions for out-" 
putting lists or cells onto stream output files. They make it possible to 
conveniently display list structures--either in a form which may subsequently 
be reread by the input function (through PRNTLST) or in a form with more 
list structure information for debugging (through PUTLIST and PUTDATM). 

CALL READLST(LST [, 'BREAK**' ] [, (jjj)] [, FILENAM]); 
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READLST is a general function for reading list structures from stream 
input files. The default file is SYSIN; this may be overridden by using 
the FILENAM argument to indicate the desired file. READLST creates a new 
list, assigns the name to I»3T, and makes its contents the structure given 
in the input file. If LST already named a valid list, that list is erased. 

The input format consists of a left parenthesis to indicate the 
beginning of the list, followed by the elements of the list, followed by 
a right parenthesis to end the list. The parantheses and the elements are 
separated from each other by one or more break characters; thus parentheses 
may be parts of elements if joined on either or both sides by nonbreak 
characters. (The default break character is the blank, but may be altered 
to any other character except (, ), or " by the argument ' BREAK=x 1 , where 
the substitute for x is the new break character . ) Sublists are entered in 
the same format within the delimiting parentheses for the higher list. 
Description lists are entered as sublists except they are preceded by 
"DLIST:" which serves as an identifier and is not interpreted as a list 
element. 

For example, 

( DLIST: ( CONTENTS NOUNS NUMBER SINGULAR ) HORSE COW ( DLIST: ( 

TYPE DOGS ) DA1MATI0N BEAGLE MUTT ) ) 

would produce a main list containing "HORSE" and "COW" and a sublist with 
dog names; each list would have a description list. 

All allowable SLIP data types may be read in; for each element, the 
decision of which data type to assign is based on the element itself and 
whether or not either option ' B' or option ' T' is selected. If option *T * 
(for text ) is chosen, all elements are assumed to be character string 
variables (ID = 9)* The table below indicates the ID selections for the 
default condition and for 'B' (fft ffi inary ). 
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Input Element Form 


ID Assignment 


Examples 




default 


' B’ 




[ + ] dddddd 


1 or 2 


5 or 6 


123 +57 1011101 -999999 


[ + jbbbbbbbbB 


1 or 2 


1 or 2 


-1011101B IB OB 


( ♦. jddd.ddd 


7 or 8 


7 or 8 


.01 1.0 -.00001 " 123 . 


[ + jbbbb .bbbbB 


7 or 8 


3 or 4 


+.01B 11.01B 1010 101 . B 


’bbbbbb'B 


10 


10 


' 100 ' B ' l'B '0* B 


(all else) 


9 


9 


WORDS '101' .833E+15 



Note. — "d" stands for any decimal digit 0-9; "b" stands for either 
binary digit, 0 or 1 . 



The choice between adjacent codes 1 and 2, 3 and 4, 5 and 6 , and 7 
and 8 depends on the length of the number. If a fixed decimal number has 
5 digits or less, or a float decimal number has 6 significant digits or 
less, or a fixed binary number has 15 bits or less, or a float binary number 
has 21 significant bits or less, it is given the ID of the shorter precision. 
If numbers are longer than 15 or l 6 digits or 31 or 53 bits (fixed and 
floating point, respectively) the most significant extra places are lost. 

Bit strings (ID = 10) may contain up to 2048 bits. Character springs may 
have up to 256 characters. 

The data representations correspond to the form for constants written 
in PL-I programs with one exception: character strings are stored in toto ; 

delimiting single quotes (') are not necessary and, if present, are stored 
as part of the string. E-format numbers are not allowed; they would be 
interpreted as character strings. 

The binary option (’B 1 ) allows one to read fixed or float decimal or 
binary. Because it is awkward to write binary numbers and because the 360 
performs fixed decimal arithmetic slowly, the default option assumes that 
any number should be stored as either fixec binary or float decimal. 

(These are the default PL-I data types also.) 
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It is sometimes handy to create list structures in which a single list 
is a sullist ot two or more points--or is its own suulist. To read such 
lists, one can indicate each repeated list by assigning it a distinct number 
the first time the list is read and simply repeating the number whenever the 
list is to be rereferenced. The numbers need not form any sequence. 

For example, 

("83" THIS LIST REPEATS ( THIS ONE DOESN'T ) (" 83 " 

) DLIST : (" 83 " ) ) 

The main list is its own sublist and its own description list. Note that 
unreprated lists need no index number. Note also that there is no space 
separating the left parenthesis from 'ohe index, but there is one between the 
index and the right parenthesis. 

In record-oriented i/O, it has been customary for lists to begin in 
the first column of a card or record. No such restriction is relevant to 
stream i/O. In the current implementation of READIEST, the Input file is 
read in 80 -character segments. A new segment is read at the start of each 
call to RHADI£T. Therefore one must begin each list beyond the 80-character 
block which contained the end of the previous list or after the end o r 
previous data read by a GET statement. To be safe, allow at least 80 
characters before the start of any list . (Or, if one is really using card 
input with only lists in the input stream, it is more convenient and 
equally reliable to start each list on a new card.) 

Notes. The characters between the end of one list and the start of 
another need not be break characters; they may be anything except left 
parentheses, such as phrases identifying the contents of the coming list. 

READI£T will scan only three 80-character segments for the start of 
a list. If it has not found a left parenthesis in those 240 characters, 
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KEADLST will jirint an error message and return control without creating a 
new list. 

CALL PRNTLST ( 1ST [, 'BREAK=x' ] [, 'B'] [, FILENAM]); 

PRNTLST prints the contents of the list structure named LST on an 
output fiie--either SYSPRINT or, if the FILENAM argument is present, 

FILENAM . 

The output format is identical to that required by READLST: lists 

are delimited by parentheses ; description lists are printed as sublists 
with the label DLIST: in front of the left parenthesis, etc. The default 

break character is the blank; it may be changed to any desired value 
except (, ), cr " by using the 1 BREAK=x ' argument. 

If the argument 'B' is omitted, i.e., the default is chosen, numbers 
are printed as either fixed or float decimal values. If 'B' is chosen, 

data with ID = 5-8 are printed as decimal numbers and data with ID = 1-4 

are printed as fixed or float binary numbers. Character and bit string data 

are printed as indicated for READLST under either option. Since binary 

numbers are difficult to interpret visually, one should prefer the default 
printing style unless he wants to preserve the distinction between binary 
and decimal machine representation. 

Within the list structure, if a list is referenced more than once, it 
is given an index number for the first appearance of the list; the index 
number alone appears for each additional reference to the list. The number 
is, in fact, the name of the lis t--the address of its header --printed in 
hexadecimal. 

CALL PUT LIST (LST ); 

CALL FUTDATM ( PNTR ) ; 

PUTL1ST and PUTDATM are intended more as debugging aids than as con- 
venient list output devices. PUTDATM prints the contents of the single 
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cell addressed by PNTR, which may be the name of a header cell as veil as 
of any data cell. PUTLIST prints the list named by LST, one cell per 
printed line, including sublists but excluding description lists. 

Printout for each cell consists of its ID, LNKL, LNKR, and the datum; 
for a header cell, this includes two items: the name of the description 

list and the reference counter. 

All items which are addresses --LNKL, LNKR, and sub list and description 
list names --are printed as hexadecimal constants. Other data are printed 
in forms consistent with the data types. 

The Reader Facility 

In order to take full advantage of the power of list processing, the 
user must have some general means of scanning lists whose exact structure 
could not be known during the programming. Readers provide such a mechanism. 
A reader is essentially a pointer which can be moved through a list struc- 
ture to find certain data or data types, can be backed up or moved forward, 
and can perform these activities in a list structure of any degree of 
complexity. 

Readers are specialized SLIP cells made up of 4 words organized as 
shown below: 



Reader field 


m 


LINK 


LVLCNT 


LOFRDR 


CELLPNT 


Bytes 


0 1 


1-3 


4-7 


8-11 


12-15 



The ID for such cells is 13. In place of the usual LNKL is a LINK address 
which points to the next reader cell on the stack, if any (a new reader 
cell is generated for each level descended into the list's sublist 
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structure). In place of MARK and LNKR is the integer LVLCNT, which is the 
number of levels into the list structure the reader has descended as well 
as the number of additional cells in the reader stack. LOFRDR is the name 
of the list (or sublist) currently being scanned, and CELLPNT is the 
address of the actual cell being pointed to. 



Example 5* 

This example shows two slightly different procedures for counting the 
sublists in a list structure. The first counts only the sublists on the 
main list. LST is the name of the list, RDR a pointer variable which will 
be the name of the reader, and FLAG is a bit string 1 bit long. 



RDR = RDROF(LST); 



N - 0; 

I 11; 

LOOP: CALL ADVLNR(RDR, FLAG, I ) ; 



IF -FLAG THEN GO TO NEXT; 
N » H + 1; 

GO TO LOOP; 

NEXT: CALL ERASRDR ( RDR ) ; 



A reader is created for LST and RDR is 
given the address of the reader cell. 
Initially the reader points to LST's 
header. 



The reader is advanced to the first cell 
on the main list which contains a sublist 
name--i.e., has an ID of 11. FLAG = 'l'B 
if a sublist name was found; 'O'B if none 
was found. ADVLNR ( adva nce linearly to 
the right) moves the reader down the list 
but does not move it into sublists. 



At this point N = the number of sublists 
in the main level. ERASRDR erases the 
reader cells since there is no further 
need for the reader. 



The second version counts all of the sublist name cells in the entire 
list structure. CELL is another pointer variable; MARK and SETMARK are 
functions for testing and changing the MARK portion of SLIP cells. 
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RDR = RDROF(LST) ; 

N = 0; 

I = 11; 

LOOP: CALL ADVSTR(RDR, I,FLAG); ADVSTR (advance structurally to the right) 

will move the reader through LST's entire 
structure, entering sublists as they are 
encountered* 



IF -FLAG THEN GO TO NEXT; Quit when the scan has gone through the 

entire structure, as before. 

CELL = CELLFNT(RDR) ; CELL is given the address of the cell 

actually pointed to by the reader. 



IF MARK(CELL) = 0 THEN DO; 
N = N + 1; 

CALL SETMARK(CELL, i); 
END; 

GO TO LOOP; 



As each sublist cell is counted, it is 
marked so that it won't be counted twice — 
as it would, for example, if the same 
sublist was referenced twice and it had 
one or more sublist cells. 



NEXT: IF N >0 THEN DO; Erase any marks that were made during 

RELOOP: CALL ADVSTR(RDR, I, FLAG) ; the counting process. 

IF FLAG THEN DO; 

CALL SETMARK(CELLPNT(RDR) 

> 0 ); 

GO TO RELOOP; 

END; 

END; 

CALL ERASRDR(RDR) ; 



RDR = RDROF(LST); 

If LST is the name of a list, then RDROF creates a reader cell for 
that list and assigns the address of the ceul to RDR. The reader initially 
points to the header of LST— i.e., its LOFRDR and CELLENT sections both 
contain the address of the list. 

RDR2 = COFYRDR(RDRl); 

If RDR1 is the name of a reader, a copy of the entire reader stack is 
made and RDR2 is made the name of the copy. This function is useful in cases 
in which one may want to make several different scanning passes at a list 
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after reaching some point in the lift. The copy insures that one can 
always come back to the same point for the next scan. 

CALL ERASRDR(RDR) ; or LVL = ERASRDR(RDR) ; 

ERASRDR erases the reader named by RDR; all the cells in the reader 
stack are returned to AVSL. If LVL is present, it is set to the LVLCNT 
of the reader- -i.e . , how many lists deep into the list structure it had 
descended. 

CALL ADVSTRfRDR [, DATID] [,FLAG]); or PNTR = ADVSTR(RDR [, DATID] [ , FLAG ] ) ; 

CALL ADVSTL(RDR [ , DATID] [,FLAG] ) ; or PNTR = ADVSTL(RDR [, DATID] [,FLAG]); 

CALL ADVLNR(RDR [, DATID] [,FLAG]); or PNTR = ADVLNR(RDR [, DATID] [ , FLAG ] ) ; 

CALL ADVLNL(RDR [, DATID] [,FLAG] ); or PNTR = ABVLNL(RDR [, DATID] [ , FLAG] ) ; 

These functions perform the actual scanning operations. They may 
move the reader to the right (downward) via ADVSTR or ADVLNR, or to the 
left (upward) via AEVSTL or ADVLNL. If it encounters sublists on the list 
being scan >ed, the reader may move structurally into the sublist via 
ADVSTR or ADVSTL or it may continue linearly along in the same list via 
ADVLNR or ADVLNL. 

If called in assignment statements, the reader advance subroutines 
give PNTR the address of the cell advanced to, unless the advance fails 
to find a proper datum cell, in which case PNTR is set to NULL. 

In the full argument list, RDR is a pointer variable naming the reader, 
FLAG is a bit string of length 1 whose value is set to 'l'B if an accept- 
able datum is found and 1 0'B if none is found, and DATID is a binary integer 
with values between 1 and 11 to indicate the type of data cell to be found. 
FLAG and/or DATID may be omitted from the calling sequence. If DATID is 
omitted, any data cell may satisfy the scan. 
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If RDR is advanced by ADVLNR or ADVLNL, the following actions take 

> 

, place: (a) CELLPNT is made equal to the address of the next cell to the 

k 

right (left) of the one it was pointing to. (b) If the new cell is the 
header of the list (i.e., LOFRDR = CELLRTT), FLAG (if present) is set to 
'O'B, and the function returns, (c) Or, if the ID of the new cell = DATID 
or if DATID was omitted, FLAG (if present) is set to 'l'B; FNTR (if present) 
is given the cell's address, and the function returns, (d) Otherwise, an 

► 

acceptable cell hasn't been found, but the list has not been completely 

1 scanned, so step (a) is repeated. 

If RDR is advanced via ADVSTR or ADVSTL, the same basic scanning process 
occurs except for modifications which allow RDR to scan the entire list 
structure rather than just the top level, (e) When the reader is advanced 
to a cell containing a sublist name (and that isn't the desired datum type), 
a new reader cell is created for the sublist (pointing initially to the 
header of the sublist). The scan then continues in that sublist, searching 
its cells for the type of datum desired. (This process may repeat endlessly, 
allowing sublists of sublists of sublists, etc., to be scanned.) (f) If 
the scan fails in a sub list (i.e., lands back on the header without finding 
a proper target), the reader cell which was created for that sublist is 
erased and the scan continues, in the list one level higher, with the cell 

• one to the right (left) of the one which had named the sublist. 

No matter how simple or complex the past scanning of a reader, it may 
be advanced further by any of the four AD V functions. In particular, 
there is no problem with advancing a reader via ADVLN which had been left 
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pointing in a sub list of the main list by a previous ADVST_ call, (in such 
cases, the reader acts like a linear reader of the given sublist.) 

Mote . ADVSTR and ADVSTL have built-in protection against list struc- 
tures which loop back on themselves. By SLIP standards, for example, it 
is fine to construct a structure of lists A and B such that each is a sub- 
list of the other. In such a structure, an unsophisticated reader could 
enter sublisbs indefinitely without ever running out of sublists, since 
it would be tracing a loop. Therefore, when ADVSTR or ADVSTL is asked to 
enter a sublist, it checks the reader's stack to make sure the sublist 
is not one which, at a higher level, RDR is already scanning. If this is 
true, RDR is advanced linearly to the next cell beyond the one with the 
sublist name, just as is normally done by ADVLNR and AJDVLNL. 

CALL INITRDR(RDR); or RDR2 = INITRDR(RDR) ; 

INITRDR initializes the reader within the list currently being scanned- 
that is, the reader is set pointing at the header of whatever list or sub- 
list is currently being scanned, (if the reader was already pointing to 
the header, no change occurs.) RDR2, if present, is given the name of the 
reader . 

CALL LVLRVT(RDR) ; or RDR2 = LVLRVT(RDR); 

CALL LVLRVTl(RDR) ; or RDR2 = LVLRVTl(RDR) ; 

These functions move a reader back up a list structure. The reader 
may back up one level (with LVLRVTl) or as many levels as necessary to 
reach the top level (with LVLRVT). (Each step of backing up is accom- 
plished by popping the top cell off the reader, leaving the reader pointing 
to the cell from which it had entered the lower sublist.) The reader is 
left pointing to the cell of the proper level from which the reader had 
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descended. If the reader was somewhere in the top level when either func- 
tion was called, there would be no action taken. RDR2, if present, is set 
to the name of the reader. 

Programming note . These functions, along with INITRDR, are useful 
for reinitializing a reader without having to erase it and then create a 
new one. The statement CALL INITRDR(LVLRVT(RDR)); first brings the reader 
back into the main list and then makes it point to the header; this is 
exactly as the reader was when first formed. 

CALL REED(RDR, DATM) ; 

REED sets DATM equal to the datum of the cell currently pointed to by 
RDR. It assumes the data types match, (if the reader points to a list 
header, no assignment is made.) 

Programming note . If REED is only used to assign a single data type, 
it may be declared as a function which returns that type and then used in 
statements like DATM = REED(RDR);. 

INT = LVLCNT ( RDR ) ; 

INT is given the LVLCNT value for the reader named RDR. If the reader 
is in the top level of the list, INT = 0; if the reader is in a sub list, 

INT = 1; if the reader is in a sublist of a sublist, INT = 2; etc. 

LST1 = LOFRDR(RDR); 

LST1, a pointer variable, is given the name of the list currently 
being scanned by RDR. This may be the list for which RDR was originally 
created, if LVLCNT = 0, or it may be the name of any of the list's sublists. 

CELL = CELLPNT(RDR) ; 

CELL is given the address of the cell currently being pointed to by 




the reader. 
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CALL SEARCH ({^ R ] , 
or FLAG = SEARCH ( ( 



DATM, DATID [, PTR] ); 

1ST 

RDR } , DATM, DATID [, PTR]); 



SEARCH scans the list I£5T fox an occurrence of DATM, which is a datum 
of the type with ID = DATID. If the search is successful, the argument PTR 
(if present) is given the address of the cell in which the datum was found 
and FLAG (if present) is set to 'l'B. If the search fails, PTR is set to 
NULL and FLAG = 'O'B. 

The search always proceeds by means of a reader advanced by ADVSTR; 
thus if DATM is on LST or any of its sublists the search succeeds. 

If the first argument is LST, the name of the list, then the search 
begins at the top of the list. If one wanted to search for different 
occurrences of the same datum, for example, an alternative exists. One 
can create a reader for the list (e.g., RDR = RDROF(lBT);) and then use 
the reader as the first argument in the calling sequence. Then SEARCH 
scans LST from the cell at which the reader was pointing. The following 
code, for example, will count the occurrences of THE on LST : 



N = 0; 

RDR = RDROF ( LST ) ; 

LOOP: FLAG = SEARCH(RDR, 'THE', 9 ); 
IF FLAG THEN DO; 

N = N + 1; 

GO TO LOOP; 

END; 

CALL ERASRDR(RDR) ; 



Description List Functions 

Any list may have a description list, and that description list may 
have any structure desired. Classically, however, description lists have 
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been thought of as lists of attribute dimensions plus values for those 
dimensions which define or describe the main list. For example, if a 
list is NEWCAK, it might have these attributes and values: MAKE, STUTZ- 

BEARCAT; PRICE, 8350; YEAR, 1970; STYLE, CONVERTIBLE; COLOR, BURGUNDY; etc. 

This type of description list is organized as a linear list with 
adjacent cells representing attribute -value pairs. The top cell of the 
list is the name of the first attribute dimension (e.g., MAKE), the cell 
below that is the list's value on that dimension (e.g., STUTZ -BEARCAT), 
etc. The functions described below are used to add, remove, and locate 
attributes and values on such a list. 

Example 4 . 

This example shows the use of description lists in the context of 
another card problem. The procedure PLAYHI is intended (for bridge, say) 
to play a card on a trick to which other cards have already been played. 
From HAND, PLAYHI must select a card from the right suit and make it either 
the highest card in the hand's suit, if it will beat the cards already 
played, or the lowest card in the suit. 

Let us (and PLAYHI) assume that HAND contains 4 sublists, one per 
suit, each having whatever cards of that suit the hand contains arranged 
by rank, with the highest card at the top. Let each sublist also have a 
description list with the following attribute pairs: NAME, (SPADES or 

HEARTS or DIAMONDS or CLUBS); NUMBER. OF. CARDS, (#); and RANKS (sublist 
with integers from 1 (deuce) to 13 (ace) for each of the cards the suit 
has) . 
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PLAYHI : PROC (HAND, SUITNAM, RANKHl) CHAR (20) VAR; 

DCL (RDR, HAND, PSUIT, PNTR) PTR, RDROF RETURNS (PTR), 

(NAME, SUITNAM ) CHAR (8) VAR, RETN CHAR (20) VAR, 

RANKHl FIXED BIN, NEWVAL ENTRY 

(PTR, , FIXED BIN,, FIXED BIN), ITSVAL ENTRY (PTR,, FIXED BIN,), 

TOP RETURNS (FIXED BIN), (POPTOP, POPBOT ) RETURNS (CHAR (20) 

VAR), ADVLNR GENERIC (ADVLNR4 ENTRY (PTR) RETURNS (PTR)), 

CONTS RETURNS (PTR), SUIT PTR BASED (PSUIT); 

RDR = RDROF(HAND); PSUIT is set pointing to the datum of 

LCOP: PSUIT a ADVLNR ( RDR ) ; the new cell; thus SUIT becomes the 

PSUIT = CONTS (PSUIT ) ; name of the next suit sub list. 

CALL ITSVAL(SUIT, * NAME ' , 9, NAME); NAME is given the SUIT'S 

value on the attribute NAME. 



IF NAME- = SUITNAM THEN GO 

TO LOOP; 

CALL ITSVAL(SUIT, 'NUMBER. OF- 
CARDS’ ,9, N); 

IF N = 0 THEN DO; 

RETN = " ; 

GO TO SCOOT; 

END; 

CALL NEWVAL (SUIT, 

'NUMBER. OF. CARDS', 9, N-l,l); 

CALL ITSVAL (SUIT, 'RANKS ',9, 

PNTR); 

N = TOP ( PNTR ) ; 

IF N > RANKHl THEN DO; 

CALL POPTOP(PNTR); 

RETN = POPTOP(SUIT) ; 

END; 

ELSE DO; 

CALL POPBOT (PNTR); 

RETN = POPBOT (SUIT); 

END; 

SCOOT: RETURN (RETN); 

END PLAYHI ; 



Scan ’mtil correct suit is found. 

N gets the integer number of cards in 
the suit. 

If no cards, return the null string 
to tell the main program so. 

Decrement the number of cards value to 
compensate for the card removed below. 

PNTR is made the name of the sub list 
with the card ranks. 

Play a card to try to win the trick. 



Play the lowest card in the suit. 



CALL MAKDLST(HOST, DLST); or LST = MAKDLST(HOST, DLST); 



MAKDLST takes two already-created lists and makes the second the 
description list of the first. If HOST already had a description list, 




37 



it is erased. 



- 36 - 



If used in an assignment statement, MAKDI£T returns the name of the 
host list. 

CALL NODLST (HOST ) ; or L3T = NODI£T(HOST); 

If the list named by HOST has a description list, it is erased and 
removed from HOST. LST, if present, is made the name of the host list. 

Both MAKDLST and NODIfiT may be used on description lists of any form. 

CALL NEWVAL (HOST, ATTR, AT ID, NUVAL, VALID [, OLDVAL]); 

On the description list of HOST, the old value of ATTR is removed 
and replaced by NUVAL. ATID is the SLIP ID of the attribute and VALID 
is the ID of the new value; both must be present. If OLDVAL is included 
in the argument list, it is given the old value for the attribute. OLDVAL 
must be of the same data type as the old value. 

If there was no old value, and in fact was no ATTR on the attribute 
list, ATTR and NUVAL are added as the bottom pair of cells on the list. 

If there was no attribute list for HOST, one is created with ATTR 
and NUVAL on it. 

Programming note . If NEWVAL is to return old values of only one data 
type, the user can declare the function to return that type and then use 
assignment statements like this: 

OLDVAL = NEWVAL(HOST, ATTR, ATID, NUVAL, VALID); 

The same procedure may be applied to ITSVAL and NOVAL, described 
next, if appropriate. 

CALL ITSVAL(HOST, ATTR, ATID, VALU); 
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ITSVAL searches the attribute list of HOST for the attribute ATTR, 
whose SLIP ID is given by ATID. If it is found, VALU is given the value 
for ATTR. VALU must be of the same data type as the attribute's value. 

CALL NOVAL(HOST, ATTR, ATID [, VALU]); 

NOVAL removes from the description list of HOST the cells with the 
attribute ATTR (which has ID - ATID) and with the attribute's value. If 
VALU is included in the argument list, it is given the value of the 
erased attribute. 

DIjST =- NAMDLST ( HOST ) ; 

If HOST has a description list, then DLST is given the name of that 
description list. 

Boolean Tests 

The functions described below are ones giving True-False answers 
about certain properties of specific lists. SLIP routines use these func- 
tions (particularly LSTNAME) to test the arguments they are given so that 
they do not blithely manipulate random storage locations. They may be 
useful in user programs as switches to .leave or enter a section of the 
program, or as tests to guard against improper manipulations. Many SLIP 
functions return nothing if given invalid arguments and, at least in some 
parts of the user program, it is desirable to check the output of such 
functions before continuing. 

FLAG = LSTNAME ( LST ) ; 

If LST is the name of a valid list,. FLAG is set to 'l'B; otherwise, 
'O'B. LSTNAME checks that the addressed cell has ID = 12 and that the 
top and bottom cells of the list in fact point back to the header. 



33 



- 38 - 



FIAG = CELLNM(FNTR); 

Tf PNTR points to a valid cell which is part of a list, FLAG ='1'B; 
otherwise, FLAG = 'O'B. CELLNAM checks that the cells to the right and 
left of the one named by PNTR point back to it and that the ID is between 
1 and 11. 

FLAG = RDRNAME(RDR); 

If RDR points to a validly -formed reader cell, FLAG = 'l'B; otherwise, 
FLAG = 'O'B. The function tests the ID of the cell and whether its LOFRDR 
points to a list and its CELLPNT points to a valid cell. 

FLAG = LSTEMTY(LST) ; 

If LST names an empty list consisting of the header and no data cells, 
FLAG = 'l'B. 

FLAG = LSTSEQL(LST1, LST2); 

FLAG = 'l'B if LST1 equals LST2, 'O'B otherwise. LST1 "ecuals" LST2 
if they both point to the same list or if (a) both list structures have 
equal data cells (ID = 1-10 ) at all points and (b) both cite the same or 
equal sublists at the same points. The list topographies must also match: 
if LST1 cites the same sublist twice, IBT2 must also cite its version of 
the sublist twice. Description lists are not checked. 

Random Number Functions 

INT = NIMBEL(LST); 

NUMBEL returns the integer number of data cells on the main list 
named LST. It does not count cells on sublists, nor does it count LST's 
header . 

PNTR = RANDEL(LST); 
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RANDEL returns the address of a randomly-selected data cell from the 
main list LST. It will not select a cell from a sublist, although it may 
select a datum cell in LST which names a sublist. 

The following functions generate random numbers according to several 
possible formats. Their use is not necessarily related to SLIP, and they 
may in fact be used in any PL-I program. The functions may also be called 
from FORTRAN programs or Assembly Language programs. 

All the generating functions a technique originally proposed by 

Tausworthe (1965) and described by Whittlesey (1968). From a starting 

64-bit random number, the next number in the pseudorandom sequence is 

generated by PP.ing operations performed by the following machine code 

(RANDUB is the 64-bit number): 

LM 2, 3, RANDUB 
LR 4,2 
LR 9,3 
SLDL 4,1 
XR 3,4 
XR 2,3 
LPR 2,2 

STM 2, 3, RANDUB 

This procedure has the advantages of high speed (for a subroutine call), 
minimum storage requirements, uniformity of distribution, and freedom 
from systematic sequential dependencies. 

CALL SETRND(DX) ; 

DX is a two-word long configuration by which the user provides the 
starting value for the generating sequence. If DX is greater than 0, it 
is used as the initial value; if it is 0 or negative, the 64-bit generator 
number is created from the current value of the computer’s clock. By 
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this latter option, a program can be written to automatically generate a 
n ew starting point every time it is run. 

The generator number is initially set to a usable value, so it is 
not necessary to use SETRND prior to using any of the following functions. 
(Suitable starting numbers ought to have almost equal numbers of 0 and 
1 bits . ) 

I = IRAND(j); 

X n RAND(Y); 

DX = DRAND(DY); 

DX * DRANDM; 

IRAND returns a binary integer between 0 and J-l, inclusively. J 
must be a positive binary integer. 

RAND returns a single word floating point number between 0 and Y-- 

*«( 

which must be a positive floating point number. 

DRAND and DRANDM return double word floating point numbers. DRANDM 
returns a value between 0 and 1, while DRAND returns a value between 0 
and DY, a double word floating point number. ( Note . To conform to 
FORTRAN'S calling conventions, DRANDM must be invoked by a statement 
such as CALL DRANDM(DX).) 

DZ = SAVRND; 

SAVRND returns the double word number used in generating the pseudo- 
random numbers in the functions above. By using SAVRND at the end of 
one day's random number generation, it is possible to initiate the 
generator with that value on the next run, via SETRND, thus continuing 
with one long sequence of numbers, (in FORTRAN, SAVRND must be invoked 
via CALL SAVRND(DZ).) 
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Other Functions 

The rest of the functions described below are ones which deal with 
cells and data storage in more detail. With the exception of the list 
marking functions, the user should have few occasions to use them. 

Cell information retrieval functions . 

INT - ID(PNTR); 

INT t. MARK(FNTR); 

POINT = LNKR(PNTR); 

POINT = LNKL(PNTr); 

If PNTR contains the address of any SLIP cell, these four functions 
return the value from their particular portion of the cell's links word. 

POINT = CONTS(PNTR) ; 

If PNTR contains the address of a SLIP cell, CONTS returns the address 
of the cell's datum. 

POINT = LINKS (PNTR); 

If PNTR has the address of the datum of a cell, LINKS returns the 
address of the cell. (LINKS and CONTS are opposites; CONTS returns 
PNTR + 8 and LINKS returns PNTR - 8.) 

INT = REFCNT(LST); 

REFCNT returns the reference counter value from the header of the 
list named LST. 

Functions for altering cell links field information . 

CALL SET ID (PNTR, INT); 

CALL SETMARK(FNTR, INT); 

SETID and SETMARK insert the value ( modulo 256 ) of the binary integer 
INT into the ID and MARK portions of the cell addressed by PNTR. Caution : 
If one uses ID values other than 1-13 for list cells, most SLIP functions 
will misinterpret or simply fail on such cexls. 
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CALL SETLNKR(PNTR, POINT); 

CALL SETLNKL(PNTR, POINT); 

SETLNKR (SETLNKL) inserts the address contained in POINT into the 
LNKR (LNKL) field of the cell addressed by PNTR. These functions should 
also be used cautiously, since they directly alter the structure of the 
list containing the cell. 

CALL SETIND(PNTR, IDVAL, LINKL, LINKR); 

CALL SETDIR(CELL, IDVAL, LINKL, LINKR); 

These functions may be used to set the ID and/or the LNKL and/or the 
LNKR fields of a SLIP cell. If one or more of the fields are not to be 
changed, the corresponding argument should be the binary integer -1 or the 
pointer variable NULL. SETIND changes the cell addressed by PNTR; SETDIR 
changes CELL itself. 

CALL MRKLSTS ( LST , INT); 

If 1ST names a list structure, MRKL3TS sets the MARK portion of the 
headers of LST and all its sublists to the value of INT ( mod 256). This 
is often useful to reset the MARKs after a scanning or searching operation 
has used header MARKs to remember which lists had been scanned. MRKL3TS 
ignores description lists. 

Miscellaneous functions . 

INT = STRLNTH(STRING) ; 

If STRING is the name of any PL-I string variable, STRLNTH returns its 
current length as read from the Dope Vector. This function is usefully 
different from the PL-I built-in function LENGTH only in the case of 
strings defined as fixed length which have been treated by SLIP as vari- 
able length. 

PNTR = NEWCELL(DATM) ; ■, A 



44 



- 43 - 



If DATM is any allowable SLIP datum, NEWCELL creates a new cell con- 
taining DATM and returns the address of the cell. The ID of the cell is 
set to the proper value between 1 and 11; the MARK, LNKL, and LNKR fields 
are 0. 

PNTR = MAKCF,LL(DATM, DATID); 

This function actually does the work of obtaining new cells from AVSL. 
DATM is stored in the cell and DATID is stored as the cell's ID. PNTR is 
given the address of the new cell. 

CALL RCELL(PNTR) ; 

RCELL actually returns erased cells to AVSL. PNTR addresses the cell 
to be returned, which can have an ID only between 1 and 11. RCELL simply 
returns the cell; in particular, it does not link other list cells around 
the removed cell. 

CALL INSERTR(PNTR, POINT); 

CALL INSERTL(PNTR, POINT); 

The cell addressed by POINT, which must not be part of a list, is 
inserted to the right (left) of the list cell addressed by PNTR. 

FLAG = COMPARE (DAT1, DAT2, DATID); 

COMPARE tests the equality of two SLIP data, both of ID type DATID, 
and returns ' l'B if they are equal or 'O'B if they are not. DAT1 and 
DAT2 must be the data themselves, not pointers to the data. Two strings 
of unequal length are considered equal if they are equal for the common 
length and if the longer is blank (for character strings) or 0 (for bit 
strings) for the extra length; this is in accord with PL-I conventions. 

CALL DSADUMP; 

CALL LDUMP(VAR, LNGTH, CODE); 



k i ; 
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Bo th these functions are intended primarily as debugging functions. 
They use the FORTRAN library function PDUMP; thus, to use them, the user 
must include the FORTRAN library (FORTLIB) in the list of libraries avail- 
able to the linkage editor and must define the standard FORTRAN output 
file in the execution step (e.g., //G0.FT^6F^1 DD SYSOUT=A). 

DSADUMP dumps the dynamic storage area of the program or subroutine 
in which the calling statement is placed. This is often useful because 
it gives the status of the 1 6 index registers at the time DSADUMP was 
called and the values of all the dynamic -allocation variables in the pro- 
gram or subroutine at the time of the call. (These are all unlabeled; the 
user must have some knowledge of PL-I program organization and a program 
object code listing to make sense of the dump.) The dump is in hexadecimal. 

LDUMP dumps the section of core storage beginning with the variable 
VAR and continuing for approximately LNGTH bytes. LNGTH may be negative, 
in which case VAR is the upper end of the dumped core. CODE is a binary 
integer indicating the form of the dump, according to the following table 
(the parenthesized values are useless in a PL-I dump): 



CODE 



Interpretation of data for output 



0 

( 1 ) 

( 2 ) 

(3) 

4 

5 

6 

(7) 

( 8 ) 

9 



Hexadecimal. 

Boolean, in byte chunks (T if at least one 1 in the 
Boolean, in word chunks. byte, F if all 0). 

Halfword binary integer. 

Fullword binary integer. 

Fullword floating point. 

Double word floating point. 

Fullword floating point, complex. 

Double word floating point, complex. 

Characters, 1 per byte. 



O 

ERLC 
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The three arguments may be repeated any number of times, so that a 
single call to LDUMP can produce dumps of different segments of core, dif- 
ferent lengths, or different output formats. 

Neither function terminates execution of the main program; thus they 
may be used to print key areas of storage several times in a single run. 



O 
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Index 


of SLIP Functions 




Name and Argument List 




Purpose 


Page 


advstr(rdr [, datid] [ , 

ADVSTL 

ADVLNR 

ADVLNL 


FLAG]) 


advance reader structurally 
(linearly) to the right (left) 


29 


BOT(LST, DATM) 




what is the list’s bottom datum? 


20 


cellnam(pntr) 




is the argument a cel^s name? 


38 


cellpnt(rdr) 




to what cell does a reader point? 


32 


COMPARE (DAT1, DAT 2 , DATID) 


compare two data 


43 


CONTS(PNTR) 




what is the address of a cell*s datum? 


4l 


copylst(orgl, copy) 




create a copy of a list structure 


17 


cofyrdr(rdri) 




create a copy of a reader 


28 


DATUM(PNTR, DATM) 




what is a cell’s datum? 


20 


drand(dy) 




random number (long floating point) 


40 


DRANDM 




unit random number (long floating 
point) 


40 


DSADUMP 




dump the program’s dynamic storage 
area 


43 


emtylst(lst) 




empty a list 


18 


eraslst(lst) 




erase a list 


18 


erasrdr(rdr) 




erase a reader 


29 


id(pntr) 




what is a cell’s ID value? 


4l 


INITAS ( [ INT ] ) 




initialize the available space list 


15 


INITRDR(RDR) 




initialize a reader within its level 


32 


insertr(pntr, point) 

INSERTL 




insert a cell to the right 
(left) in a list 


43 



ER1C 
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Natne and Argument List 



Purpose 



IRAND(J) 

ITSVAL(HOST, ATTR, AT ID, VALU) 
LDUMP(VAR, LNGTH, CODE) 

LINKS (PETR) 

LIST(LST) 

LNKL(BNTR) 

LNKR 

LOFRDR ( RDR ) 

LSTEMTY(LST) 

LSTNAME(LST) 

LSTSEQL(LST1, LST2) 

LVLCNT(RDR) 

LVLRVT ( RDR ) 

LVLRVTI(RDR) 

MAKCELL(DATM, DAT ID) 

MAKDLST ( HOST , DLST) 

mark(pntr) 

MOVER(LSTl, IST2) 

MOVEL 

MRKLSTS(LST, INT) 



random number (long binary integer) 

what is the attribute's value? 

dump core segment by length 

what is the address of the cell 
dauum' s links portion? 

create (an empty) list 

what is a cell's LNKL (LI'IKR) value? 

what is the list of a reader? 

is a list empty? 

is the argument a list name? 

are two list structures equal? 

what is the reader's level? 

revert to the top level 

revert one level back 

create a new cell 

make a description list 

what is a cell's MARK value? 

move a segment of a list to the 
right (left) in another list 

set the MARKs of the headers in 
a list structure 



namdlst(host) 



what is the name of the description 
list? 



NEWCELL(DATM) 



create a new cell 



NEWTOP(LST, DATM) put a new datum at the top (bottom) 

NEWBOT of a list 



Pu.y 



40 

yO 



4*3 



4]. 



32 



38 



37 

38 
32 
31 
31 
43 
35 



4i 



20 



42 



37 



42 

1 ? 



O 

ERIC 
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? 

* 



> 

f 



Name and Argument List Purpose Page 

NEWVAL(HOST, ATTR, AT ID, NUVAL, VALID [, OLDVAL]) 36 

give the attribute a new value 

NODI£T(HOST) remove and erase the description list 3 6 

NOVAL(HOST, ATTR, ATID [, VALU]) remove the attribute and its value 37 

NIMBEL(LST) how many elements are on a list? 38 

POPTOP(LST [, DATM]) pop the top (bottom) cell from a list 20 

POPBOT 

PRNTLST(LST [, ' BREAK=x ' ] [ , ' B ' ] [ , FILENAM] ) print a list structure 24 

PUTDATM(FNTR) print a cell and its datum 25 

PUTLIST(LST) print a list structure in debugging 25 

format 

RAND(Y) random number (floating point) 40 

RANDEL(lBT) select a random list element 38 

RCELL(PNTR) return a cell to AVSL 4-3 

RDRNAME(RDR) is the argument a reader's name? 38 

RDROF(LST) make a reader of a list 28 

READLST(LST [, 1 BREAK=x ' ] [ , {'B' or 'T')](, FILENAM]) 21 

read a list structure from stream 
input 

REED(RDR, DATM) what is the datum to which the reader 32 

points? 

REFCNT(LST) what is a list's reference counter? 4l 

REMOVE(PNTR [, DATM]) remove a cell from a list 20 

REPLACE(FNTR, DATM [, DATID][, OLDDAT]) replace a datum cell 19 

SAVRND save random number generator value 40 

SEARCH({LST or RDR), DATM, DATID [, PNTR] ) 33 

search a list structure for a datum 



0 

ERLC 
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Name and Argument List 


Purpose 


Page 


SETDIR(CELL, IDVAL, LINKL, 
SETIND(FNTR, idval, linkl, 


LINKR) set the ID, INKL, and LNKR 

LINKR) of the argument (or the cell 

addressed by the argument) 


42 


setid(pntr, int) 

SETLNXL(PNTR, POINT) 

setmark(fntr, int) 
setlnkr(pntr, point) 


set the ID (LNKL, MARK, or LNKR) 
portion of the addressed cell 


4l 


setrnd(dx) 


set random number generator value 




ST RLNTH( STRING) 


what is a string 1 s length? 


42 


subtop (lst, datm [. datid][, olddat]) 

SUBBOT substitute the top (bottom) data 

cell on a list 


19 


TOP (LST, DATM) 


what is the top datum of a list? 


20 
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Appendix A 

Running a SLIP Program 

Because SLIP is a set of library subroutines which are not stored on 
the standard system library, a few changes in job control (JCL) cards must 
be made. 

1. In the link editor stage, the library must be revised from the 

usual SYS1.PL1LIB to the following: 

//LKED.SYSL1B DD DSNAME-SYS1.PL1LIB, DISP=SKR 
// DD DSNAME-OCS .SLIPLIB, DISP=SHR 

If either LDIJMP or DSADUMP is being used, the FORTRAN library must be con- 
catenated by a third card: 

// DD DSNAME=SYS1.F0RTLIB,DISP=SHR 

2. In the execution stage , one extra output file should be declared, 
nob only for SLIP but for any PL-I program in which an abnormal job termina- 
tion might occur: 

//GO.PLIDUMP DD SYSOUT=A 

Ana, if LDUMP or DSADUMP is being used, 

//G0.FT^6F^1 DD SYSOUT=A 

One of the most time-consuming chores in writing SLIP programs is 
defining, via a DECLARE statement, all the SLIP functions one plans to use. 

In order to avoid as much of this effort as possible, an external library has 
been established with three different sets of function declarations: LISTS, 

READERS, and DLISTS. The first, and most frequently used,- defines the basic 
list functions. This segment also contains a "CALL INITAS;" statement, so 
that one need not write a separate call while using the first declaration. 
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The second declaration defines all reader -connected functions, and the 
third defines the description list functions. The contents of these 
segments, along with standard definitions for the SLIP functions not 
covered by the library, are listed below. 

To incorporate any or all of these definition segments into the user's 
program, one calls upon one of PL-I's preprocessor statements --the 
INCLUDE statement. 

At ETS, these segments exist on ETSLIB, in the partitioned data set 
OCS.SLIPTXT. One must follow these stejs in order to have access to them. 

1. Include the following data definition card in the PL-I step: 
//PL1L.SYSLIB DD DSNAME^OCS .SLIFTXT, DISP=SHR 

2. In the option list for the PL-I Job step, include the parameter 
which will cause the preprocessor to be invoked (MACRO) along with whatever 
other parameters are desired (e.g., LOAD, ATR,XREF). One may wish S0URCE2, 
which will print the program as it appears after the preprocessor pass, 

and also MACDCK, which will cause the same thing to be punched on cards. 

3. In the program, preferably before any executable statements, 
request the inclusion of the segments: 

$ INCLUDE LISTS, 'READERS, DLISTS; 
using all three segments or any two or one. 

Note. If one wishes to redefine one of the functions included in one 
of the library DECLARE segments (as, for example, to use TOP or BOT in 
assignment statements — see pp. 18 - 19 ), it is not necessary to avoid using 
the segment. Simply define the function as is appropriate to the program 
in a DECLARE statement which precedes the INCLUDE statement: PL-I will 
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accept the first definition and ignore the one which comes later, although 
the compiler will print a warning against multiple function definitions. 

There is some cost to the user when he uses these preprocessor segments. 
First, the preprocessor stage takes some computer time. Second, and more 
important, all of the functions defined are loaded from SLIPLI3 into the 
computer--whether the program will use them or not. In cases with programs 
to be run once or twice, these costs may be tolerable. For longer runs, 
this procedure seems to be the best compromise: 

1. In the first run, use the MACDCK option along with MACRO; this 
will cause to be punched a deck of the source program after the preproc- 
essor run--i.e., including the requested SLIPTXT segments. 

2. For f - ture runs, omit the MACRO and MACDCK options and run without 
the preprocessor stage (unless the program requires it for other reasons). 

3* Remove from the SLIPTXT cards the definition cards for the func- 
tions either not used in the program or redefined in earlier declarations. 
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The LISTS Text Segment 

i r. r i 

:■< ; fm try (dtp,), 

“• f“ t -< y (ptp) returns (btt(D), 

COMPARE ENTRY (,, FIXED DIN (31)) FE TURKS ( LIT ( 1 ) ) , 
C ( NTS FNTRY (DTw) PiTnPKS (FTP), 

DOT YLS I r N T '< Y (FTP, PER) RETURNS (FTP), 

:i'ir v entry (ftp,), 

V. TYLSI ENTRY (FTP) RETURNS (PTF), 

!' ■ ■' SLR T IK TRY (FTP.) P 5 TURKS (FIXED FIN ( ?1 ) ) , 
l. N T K Y (PER) RETURNS (FIXED GIN (31)), 

INI IAS ENTRY (FIXED BIN (31)), 

LIN KB ENTRY (P7R) RETURNS ( PTR ) , 
i. T p; in F f 

( I T 3 1 1 FNTRY (PTR) RETURNS (PIP), 
l 1:3X2 ENTRY ( FIX ID BIN (31)) Pi TURNS (?T D ), 

LIS 13 ENTRY (FIX'D DEC (1)) BET URNS (PTR)), 

LNXJ. ••:>l m PY (PTR) RETURNS (PTR), 

Ll-'KI UNIFY (PTR) RETURNS (PTE), 

L'i“E M TY ENTRY (PIP) P ST HP NS (BIT (1 ) ) , 

LSTNAMi ENTRY (PTR) RETURNS (311(1 )), 

1ST MOL ENTRY (PTR, PTR) RETURNS (BIT ( 1 ) ) , 

KAF.K ELNTKY (PTR) RETURNS (FIXED. -BIN 131)), 

N~W*OT GENERIC 



( NEW EOT 1 


ENTRY 


(PTE , 


FIXED 


BIN 


( 15) ) 


RETURNS 


(PTR) 


NEW BO 12 


r NTP Y 


(PTR , 


FIXED 


BIN 


(31) ) 


RETURNS 


( PTP ) 


i E w SOT 3 


ENTRY 


(PIE, 


FLOAT 


b i a 


(21 ) ) 


RETURNS 


(PTR) 


MW ROT 4 


ENTRY 


(PTP, 


FLOAT 


DIN 


(53) ) 


PETUFNS 


(PTP) 


N C to EOT 5 


ENTRY 


(PTR, 


FIXED 


nrr 


( 5>) 


BSIUFNS 


(PTRJ 


NEW ROT 6 


ENTRY 


(PTR, 


FIXED 


DEC 


( 15) ) 


RETURNS 


( PTF ) 


NEW POT 7 


ENTRY 


(PTR , 


FLOAT 


DEC 


( 6)) 


PET UP NS 


(PTP) 


N r.'to POTt: 


rjjTDy 


(PTR, 


FLOAT 


DEC 


(16) ) 


RETURNS 


( PTP) 


EEw DOT 9 


ENTRY 


(P IF, 


CHAR 


(256)) PET 


URNS (FT. 


P) , 


NEWDT9A 


ENTRY 


(FT 75 , 


CHAP. 


(2 56.) 


VAR) 


F FT U 75 NS 


( PTP) 


NEWBTi: 


ENTRY 


(PTR, 


BIT ( 2 J 4 t ) ) RET 


USNS (FTP.) , 


NUBTit A 


ENTRY 


(PTR , 


BIT (. 


29 48) 


VAR) 


P I ? U E N 3 


(PTP) 


TFto DTI 1 


ENTRY 


(PER, 


’FTP) 


RETURNS (PTR)), 




J EWTOP GFS 


ERIC 














( l.FWTOPl 


ENTRY 


(RTF, 


FIXED 


3IN 


( 15) ) 


SETUFNS 


(PTR) 


NEW TOP 2 


ENTRY 


(PM, 


FIXED 


BIN 


(31)) 


RETURNS 


(PIP) 


NEWTOP3 


E NT P Y 


(PER, 


FLOAT 


BIN 


(2.1)) 


.. JxSTUiLNS. 


_(P TP.) 


NEW TOP U 


ENTRY 


(PTR, 


FLOAT 


BIN 


(53) ) 


RETURNS 


(PTP) 


RENT CPF 


ENTRY 


(PI?., 


FIXED 


DEC 


(5) ) 


RETURNS 


(PTR) 


N E to T 0 P 6 


ENTRY 


(PIP, 


FIXED 


DEC 


(15)) 


RETURNS 


(PTR) 


NEW TOP 7 


ENTRY 


(PTR, 


FLOAT 


DEC 


( 6)) 


RETURNS 


(PTF.) 


UEWIOPfi 


ENTRY 


(PTR, 


FLOAT 


DEC 


(16) ) 


RETURNS 


(PTR) 


KtrfTOP? 


ENTRY 


(PIP,. 


CHAR... 


(2 .5 6 ).). RS.IJU.PvN.S_. (JETS.) , . 


Nr WTP9A 


FNTRY 


(PTR , 


CHAR 


(256) 


VAR) 


RETURNS 


(PTR) 


NFWTP1 0 


ENTRY 


(PTE, 


FIT (2948)) RET 


UPNS (FT! 


P), 


NUT Pi: A 


ENTRY 


(PTR, 


BIT (20 46) 


VAP) 


PETUFNS 


(PTR) 


NTWTP1 1 


ENTRY 


(PIE, 


FTP) 


RETURNS ( FT F ) ) , 




PC PLOT ENT 


RY (PTR 


,> , 












POPTOP ENI 


P.Y (PEF. 


#) -9 • 












r F IT NT ENT 


f.Y (PTR) “SlUPNS ( 


FIXED 


ETN 


(?1) ) , 




?. _ ?. C V E ENT 


RY (PIF 


,) , 




- 
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REPLACE ENTRY ( PTP, , F TXFD BIN (31) ) 

- KTJr IP", fixed bis rn 5 

bU-ror ffTfiy ( PTR -- )f 

s:, 3-OP SN TF Y (p TP,, 
r ENTRY (PTP. , ) ; 

CALL INITAS; 



FIX£n..JBULiJ.1) ,j\ 

FIX'D BIN’ (31) ,) , 



The READERS Text Segment 



^ r it 






Vi;7n ftr.N? 


*IC 




UDVSTB1 


1! N T R Y 


( P T R , 


ADVSTR2 


2UTRY 


(PTR, 


;* nvsTP ^ 


ENTRY 


(PTP, 


iD VSTF.U 


ENTRY 


(PTR) 


VfilL ft 7 HE 


PIC 




( AimiTLl 


V Jy| fp g Y 


(PTR, 



FIXED Hit: (31), BIT ( 1 ) ) PBTtlPKS 
BIT (1)) EF.IURNS CD-IS) , 

FIX'D BIN (3D) RETURNS (PTP), 
SET UENS (PTP.)), 



(P TP) 



A DV3TI.2 ENTRY 
A B VSTL3 ENTRY 
ADVSTLu EMERY 
>VDi c GENERIC 



FIXED SIN (31) , BIT ( 1 ) ) 
(PTP, BIT (D) RETURNS (PTR), 
(PTR, FIXED BIU (311) SET UP NS 
(PTR) RETURNS (PTE)), 



RETURNS (PTR), 
(PTE) , 



k ~ V 



AOVLNF- 1 


ENTRY 


(PTR, 


FIXED BIN (31 ) , BIT ( 1) ) B 


ST URN 3 (PTP), 


ADVLNP2 


ENTRY 


(PTE, 


BXIi U X — RET U-RN S -(PT-BX, .. 


_ 


h PVLNP 3 


ENTRY 


(PTP, 


FIXED BIN (3D) RETURNS 


(PTR) , 


ADVLSEtt 


ENTRY 


(PIE) 


RETURNS CPTR)), 


.. 


LNL GENE 


PIC 








ADVLNL 1 


ENTRY 


(P IR, 


FIXED SIN (3D , BIT ( 1) ) 


RETURNS (PTR) 


? DVLNLJ 


ENTRY 


(P £R, 


BIT (D) RETURNS (PTR), 




ADVLNL3 


ENTRY 


(PTR, 


FIXED BIN (3D). .RETURNS 


(PTRX,... 


A DV I.NL4 


ENTRY 


(PTR) 


RETURNS (FIR)), 





TILL PUT ENTRY l PTE) BETUBNS . (PTE) , . 

C 0 P Y [! r ' ? EVERY (PTR) RETURNS (PTR), 

E'ASRJP ENTRY (PTR) RETURNS (FIXED BIN .(31)), 
I FIT RPR ENTRY (PTR) RETURNS (PTR), 

Lor FDR ENTRY (PTR) RETURNS (PTR), 

LVLCNT ENTRY (PTR) RETURNS (FIXED BIN (31)), 
LVLrV.' ENTRY (PTR) RETURNS ..(PIE), 

LVLFVD ENTRY (PTR) RETURNS ( D T R ) , 

EDI; FAME ENTRY (PTE) RETURNS (BIT (1 ) ) , 
r i T Or ENTRY (PTR) RETURNS (PTR), 

ID- ID DUFY (PTR,); 
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The DLISTS Text Segment 



PEC LA i ?! 

71 S VAI, ENTRY (PTP,, F'XIP 3IN (.31),), 

«.* KDL5T ENTRY (P”**, Pin) rr;u“N:» (PTP), 

makjlst entry (ptto returns (riD, 

i- 1 W V A L ENTRY (PTP,, FIXED 91 N (.11) , , FIX ZD BIN (31),), 
NODI.ST ENTRY ( PTR ) RETURNS (PTF) , 
i.GVAL ENTRY ( PTF , , FIXED DIM (31),); 



The following declarations are not included on any SLIPTXT segment 
because they represent functions which are used rarely--too infrequently 
to justify keeping them present, occupying computer space, for every 
program run. The declarations below are the ones which ought to be 
used if one does wish to call on the functions: 



"CLARE 
?.Z I.AFE 
r.CLAF E 
2CLAR2 
ZCIA r:E 
SC LAP Z 
ECLAT, E 
EC I.!. PF 
r.CI A F F 
1.C L ARE 
.X L A f E 
DC L ALE 
( NZWC 
NZNC 
NEWC 



DI? AND ENTRY (FLOAT BIN (53)) RETURNS (FLOAT BIN (53)) 
DhANDN RETURNS (FLOAT BIN (53)); 

DSADtIMP ENTRY; 

INSERTS- ENTRY -(PTR, PTR) ; — 

INSERTL ENTRY (PTP, PIP); 

IP AND ENTRY (FIXED BIN (31)) RETURNS 



LDUMP ENTRY (, FIXED EIN (31), FIXED 



(FIXED PIN 

PIN (31)); 



(31)) 



MAKCELL (, FIXED BIN (31)) 
MOVER ENTRY (PTR, PTR); 

NOVEL ENTRY --CPTR, PTR-l;- 

MRKL5TS (PTP, ^IXSD BIN (31)) 
NZWCELL GENERIC 
ELI ENTRY (FIXED BIN (15)) 



RETURNS (PTR) 



EL 2 ENTRY 
EL 3 ENTRY 



(FIXED 

(FLOAT 



BIN 

BIN 



(31)) 

( 21 )) 



RETURNS 

RETURNS 

RETURNS 



( D TR) , 
(PTR) , 
(PTP) , 



N E W.CELil.- E.UTR.Y ~IE.LQA.I- BIN (53 )~) PE T U-RL LS -IP-IB), 

NEW CEL 5 FNTPY (FIXED DEC ( 5)) RETURNS (PTR), 

NEWCZL6. ENTEJL (FXXED-HEC ( 1 51 ) EETU-ENS (PTR) , 
NEWCEL7 ENTRY (FLOAT DEC ( 6)) RETURNS (PTF), 

KEWCEL8 ENTRY (FLOAT EEC ( 16 J J —RET UR. N S (PTR), 

NEWCELP ENTRY (CHAR (256)) RETURNS (PTR), 



1LEW.CL9 A ENTRY. 
NEMCL1C ENTRY 
NUC L1C A ENTRY 
NSWCL11 ENTRY 



XC.HA£. -125.6). V.AEJ. EETU2N.S (P.TR.).^ 
(BIT (2048)) RETURNS (PTR), 

(BIT (2048) VAR.) RETURNS (PTR) , 
(PTP) RETURNS (PTF)); 
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■ i- *. 

■ L 

( 



LA 
: I Art 



i' L 

P ? 

I'R.NTIS 1 
PPNTLS2 
PENILE 3 
l PNTLS U 
I R TILS 5 
PR N 'EL St 

- 5 



RETURNS (FIXED BIN (31)); 



MU*! BEL ENTRY (PTR) 

PRNTLST GENERIC 
ENTRY (P I El, 

(PTR, CHAR(I) ) , 

(PIP, CHAR ( 1 ) , CHAR(1) ) , 
(PTP, FILE), 

(PTR, CHAR (1) , FILE) , 
(PTR, CHAR (1 ) , CHAR ( 1) , 
DRY (PTR); 



ENTRY 

ENTRY 

ENTRY 

ENTRY 

ENTRY 

FUTDAE 



FILE) ) ; 



K 



P!1TL‘ 



ENTRY (FTP); 



C T. A •• E 


RAND EN 


TFY (FLOAT BIN (21)) 


RETURNS (FLOAT 


C LA ! l 


0 AN del 


FN1RY (PTR) RFTUPNS 


(PEP) ; 


' 1 1 IT t* 


?C ELL E 


NT AY ( PTP ) ; 




c i. « r £ 


b ha dls r 


G - - NFRIC 




ULA 


DlS " ENTRY 


(PIP.) , 




:■ r 


r I.s: ENTRY 


( or P , CHAR (1 ) ) , 
(PIP, CHAR (1), CHAR 




t i 


i.’LSj ENThY 


(1>) , 


, ’ . , ( \ 


1' LS u ENTRY 


(P7F, ETLF), 




Z. i* 


MS 5 ENTRY 


(PIP, CHARM) , FILE) 


t 


\ ■ * * 


PL SB SNTrY 


(PT’R, CHAR (1), CHAR 


(1), RILE)); 



BIN (21)); 






i •. 

LA 

LA 

r a ■ 



RETURNS (FLOAT DIN (53)); 

ENTRY (PTE,, FIXED BIN (31), PTR) RETURNS 
ENTRY (, FIXED PIN (31), PTE, PTE) ; 

LN1PY (PTR, FIXFD BIN (31), PTR, PTR); 

N TRY (PTR, FIXED EIN (31).); 

ENTRY (PTR, PTR); 



S AVEND 
S EAR C H 
SET DIF 
S IT INI) 

Z FT ID E 
SFTLNKL 
.SETLNKK ENTRY 
SET PND ENTRY ; 

STKLNEH RETURNS (FIXED BIN 



(BIT ( 1 ) ) ; 



(DTP., PTP) ; 



(31)); 
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Appendix B 

SLIP Error Facilities 

Although SLIP is a subroutine language operating within PL-I, the 
PL-I diagnostics are generally unhelpful for locating an error in list 
processing. There are two reasons for this: first, SLIP performs opera- 

tions which are outside the realm of normal PL-I capabilities ; and second, 
SLIP subroutines take some liberties and violate some assumptions of PL-I 
programming in being able to accomplish their ends. 

The major violation of PL-I standards is in allowing argument lists 
of variable length for the subroutine calls. While taboo in PL-I, vari- 
able length argument lists are common to most other languages and have been 
artificially preserved in SLIP. This allows the user much more flexibility 
than fixed-length argument lists but makes most of PL-I's error messages 
on argument lists inapplicable. 

An advantage to PL-I is that its error messages have several levels of 
severity. The philosophy seems to be to inform the user if he has made 
a mistake but then allow his program to run as far as possible aryway. 

This works ideally with SLIP, in which these "mistakes" are made quite 
frequently and purposefully. 

SLIP contains some brief error detec i facilities of its own. SLIP 
attempts to keep the user's program running as long as possible and to 
allow the user as much freedom as possible. There is only one condition 
for which SLIP will terminate a program: lack of space, which makes it 

impossible to create new cells. In all other cases, SLIP subroutines check 



O 

ERIC 
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to make sure that its list manipulations are actually being done to lists; 
if not, a warning is printed and execution continues without the asked -for 
manipulation. These checks are intended to provide the user with some 
indication that his program may be misperforming and to prevent it from 
doing something so wrong that the PL-I monitor will detect an error and 
halt execution. 

If the user's program is going very wrong, then repeatedly calls to 

SLIP functions will have invalid arguments and a great amount of computer 

time might be wasted* To counteract this, SLIP counts the calls to its 

error routines. If the calls exceed a certain number (by default 50; if 

may be set to any desired value, though, by including the value as an 

argument to INITAS; see p. 15 above), execution is stopped, the following 

error message is printed, and the standard PL-I error condition is raised: 

**** SLIP ERROR TALLY HAS REACHED nnnn. PROGRAM EXECUTION HAS BEEN 
TERMINATED AT THIS POINT- 

INITAS has two error messages to indicate that no more space could be 
found for list storage and the program is therefore halted; these were 
listed on p. 9* 

Several functions require one or more list names as arguments. Because 
they must perform manipulations based on the list names, they test this and 
in general do nothing if they have been given nonnames. The following 
error message is printed in such cases: 

**** fname WAS CALLED WITHOUT A LIST NAME (OR NAMES) IN ITS ARGUMENT LIST- 
**** THE FUNCTION EXITED WITHOUT DOING ANYTHING- 

The name of the function is inserted in the first line. The functions 
which do this include COPYLST, EMTYLST, ERASLST, ITSVAL, LSTSEQL, MAKDLST , 
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MOVER, MOVEL, MRKLSTS, NAMDLST, NEWVAL, NODLST, NOVAL, NUMBEL. PRNTIST, 
PUTLIST, RANDEL, and RDROF. 

Other functions have slightly different argument requirements, or 
detect other types of errors. Their main comment lines, which appear 



with a reminder that the function did nothing, are listed below: 



ADVSTR 

ADVSTL 

ADVLNR 

ADVLNL 

COPYRDR 

ERASRDR 



REQUIRES THE NAME OF THE READER OF A VALID LIST IN ITS ARGUMENT 

LIST. 



BOT 

DATUM 

TOP 



! was asked to return the datum of something which was not a slip 

DATA CELL. 



ITSVAL 

NOVAL 

NEWBOT 

NEWTOP 



WAS GIVEN THE NAME OF A LIST WITH NO DESCRIPTION LIST. 

REQUIRES A LIST NAME OR LIST CELL ADDRESS AS ITS FIRST ARGUMENT. 



! NEWTOP ) 

NEWBOT > REQUIRES 

newcell) 



POPBOT | 

POPTOP ? WAS ASKED TO ERASE SOMETHING WHICH WAS NOT A SLIP DATA CELL. 
REMOVE ) 



PUTDATM REQUIRES THE ADDRESS OF A SLIP CELL AS ITS ARGUMENT. 

READLST COULD NOT FIND THE START OF A LIST WITHIN 240 CHARACTERS. 
READLST FOUND SOME CHARACTERS WHICH COULD NOT BEGIN A LIST. 



SEARCH REQUIRES THAT ITS FIRST ARGUMENT NAME A LIST OR A READER. 



SUBBOT 

SUBTOP 

REPLACE 



WAS ASKED TO SUBSTITUTE A NEW DATUM IN PLACE OF SOMETHING WHICH 
WAS NOT A SLIP DATA CELL. 
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Appendix C 

Subtle Features of PL-l(F) 

For the average user of PL-I and SLIP, it is adequate to know the 
information presented to this point. For the user who may wish to attempt 
things slightly outside the normal applications of SLIP, and for the user 
who reads and is concerned with the PL-I compilation error messages which 
commonly accompany SLIP, the following section is intended. 

Function and Subroutine Conventions 

PL-I almos t follows standard OS conventions in the way it sets up and 
manipulates function calls and argument lists. By convention, the argument 
list of a function is represented by a string of word-long addresses which, 
in order, point to the actual first, second, etc. arguments to the func- 
tion. This address string is in turn addressed by the value in General 
Register 1 (out of 16 , numbered 0 through 15). Because OS allows variable - 
length lists of arguments, there is normally a flag set in the last address 
in the list to indicate that it is the address of the last argument; this 
flag is simply a minus sign— i.e., the first bit in the last address is 1. 

PL-I sets up its argument list in the same way. Although PL-I does 
not "allow" variable -length argument lists, and thus has no need for 
flagging the last argument address, PI, -I does flag the address in order 
to be consistent with OS conventions. 

There are two differences, however. If a FORTRAN function, for example, 
is to return a value, the function leaves the value in a conventional spot 
and the calling program retrieves it. Since PL-I may return anything 
which is a valid data type, PL-I can't reserve a conventional spot 
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sufficiently flexible to accept any return value. Therefore, PL-I arti- 
ficially takes the recipient of the function's value and makes it the final 
argument to the call. This is why, for example, the normal call for TOP 
(e.g., CALL TOP(LST, DATM);) can be redefined so that DATM = TOP(lBT); is 
acceptable. Both statements generate a call to TOP which appears to have 
two arguments. 

The second difference appears to be a compiler error, but one requir- 
ing enough coincidences that it is unlikely to bother the user. Because 
of SLIP's non-PL-I treatment of arguments, however, program errors due to 
this are extremely hard to detect and the problem deserves description. 

Under certain circumstances, PL-I will flag an address which is not 
the final argument address; this makes it appear that the argument list is 
shorter than it actually is. This may happen if the function call comes 
from within a subroutine and the final parameter to the subroutine is a 
nonfinal argument in the function call. For example: 

DUMMY: PROG (VAR, VARY); 

• • • 

CALL VERYDUM(VARY, X, Y, Z); 

• • • 

END DUMMY; 

In coding the call to VERYDUM, PL-I uses the address of VARY as taken from 
the argument list to DUMMY. Since VARY was the last argument to DUMMY, its 
address was flagged; PL-I does not remove the flag before putting the 
address into VERYDUM 1 s argument list. 

If VERYDUM is a function whose operation depends on the number of 
arguments it thinks it receives, it will operate not as intended since it 
will find it has only one argument. 
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Many SLIP functions count their arguments and respond differently for 
different numbers of arguments. They have been programmed around this 
compiler quirk for their own calls to other SLIP functions, but the user 
can run into this problem if he writes subroutines which call SLIP func- 
tions. 

SLIP uses variable length argument lists in two ways: first, by 

allowing certain arguments to be dropped from the list if they are unwanted 
(e.g., CALL PRNTLST ( LST , 'BREAKS.', OWNFILE); vs. CALL PRNTLST ( LST ) ; ) ; and 
second, by letting functions return values or not (e.g., CALL ERASLST 
(LST) ; vs. ICOUNT = ERASLST (LST );) . PL- I does not allow such things, and 
it objects during compilation with different degrees of severity: 

1. CALL ERASLST(LST); and ICOUNT = ERASLST(LST) ; PL-I codes both 

correctly and issues no warning; PL-I seems completely blind to this kind 
of violation. PL-I will object, however, if the function is to return a 
data type not compatible with the recipient: RANDEL normally returns a 

pointer value; the incompatible INT = RANDEL(li3T) ; would be rejected, 
although it would be fine if RANDEL was defined as returning a fixed 
binary number. 

2. DCL COPYLST ENTRY (PIR, ETR) RETURNS (FTR); and COPY = COPYLST 
(ORGL); The call will be coded as written, which is acceptable to COPYLST, 
and the following severe error message will appear: 

IEM0787I INCORRECT NUMBER OF ARGUMENTS FOR FUNCTION zzzz IN STATEMENT 

NUMBER xxx 

3 . COPY = COPYIET ( ORGL, COP); and COPY = COPYLST (ORGL) ; Both 
statements will be coded as written but this warning will be printed: 
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IEM079H NUMBER OF ARGUMENTS FOR zzzz STATEMENT NUMBER xxx INCONSISTENT 

WITH NUMBER USED ELSEWHERE 

5. Incorrect matching of argument attributes with parameter attribute 

definitions. For normal functions, this combination will result in a data 
conversion if possible or, if not, statement deletion: DCL SETID ENTRY 

(FTR, FIXED BIN (3l)); and CALL SETID(LST, X); If X is a float decimal, 
for example, conversion wil. take place. For generic functions, an 
attribute mismatch will terminate compilation. 

6. Generic functions. From Appendix A, it is apparent that SLIP 
uses generic functions extensively. Generic functions allow the user to 
specify only the generic name in his program and have the compiler auto- 
matically select the proper entry. Such functions allow greater flexibility 
and power in the writing of the subroutines. In functions like NEWTOP 

(pp. 19 and 54), for example, the entry point tells NEWTOP the type of 
datum to be put in a SLIP cell. 

Generic functions are also extremely unforgiving. One must specify 
completely all the arguments' attributes and the return attributes, if 
any (although even generic functions don't care if the executed statement 
requires a returned value or not). And if attributes in the declaration 
don't match the attribute in the calling statement, compilation is termi- 
nated rather than data conversion attempted. 

For numeric data, precisions must match perfectly: if NEWT0P1 requires 

a second argument with FIXED BIN (15) attributes, an argument with FIXED 

BIN (14) attributes will cause termination, even though both types of 
\ 

variables have the same physical representation. 
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For string data, the length of the string is not considered in Uu 
matching. Although NEWT0P9 is declared v/ith t. second argument whose attri- 
butes are CHAR (2p6), a fixed length character string of any length wii 
satisfy the requirements. No string of varying length will, however; 
thus; the parallel entry NFWTP9A • 

Based Variables and Dope Vectors 

Baced variables consist of a (potentially existing) variable and a 
pointer which addresses the location of the variable. Based variables 
exist only when the pointer has been given a valid address, either through 
an A.LLOCATE statement or by ar. assignment statement or subroutine . all 
which gives the pointer some value. For SLIP, based variables tend to be 
quite useful as a means of gaining access to list information. For example 
if the declaration DCL DADDR PTR BASED (DPOINT); exists and CALL LIST 
(DP0IN7); is executed, DADDR is the LNKL address of the header of the list 
(plus the ID, which does not interfere with the address potential of DADDR') 

Based variables which are scalars without Dope Vectors are uncompli- 
cated: if the base pointer variable contains an address, then the variable 
is seen as being at that, location. 

Based variables which have Dope Vectors, such as strings and arrays, 
are more complicated. This is primarily because the base pointer, which 
addresses the variable, and the Dope Vector pointer, which addresses the 
variable, usually do not hold the same value. 

For arrays, the Dope Vector consists of the virtual address of the 
array element whose subscripts are all 0 and multipliers for determining 
the location of any element given its subscripts. This virtual address is 
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usually outside the physical limits of the array. For a based array, the 
base pointer contains the address of the first actual storage location for 
the array, regardless of its subscripts. Whenever the array is referenced 
a dummy Dope Vector is created with its address derived from the pointer's 
value to reference the O-subscript element. 

Based string variables may not have the VARYING attribute because of 
the way PL-I deals with based string Dope Vectors. There is a single 
dummy Dope Vector, even though the string may have been ALLOCATEd into 
any number of locations. In normal string manipulations, PL-I needs the 
address of the Dope Vector, which indicates where and how long the string 
is. In based string manipulations, the base pointer contains the address 
of the start of the string itself, rather than the address of the Dope 
Vector. For each manipulation, PL-I creates a Dope Vector from the base 
pointer and the dummy Dope Vector, which contains only length information-. 

Because of this, it is somewhat difficult to retrieve a string datum 
from a list cell by means of based variables. If VSTR is a variable -length 
string, CELLAD is the address of a string-holding cell, PNTR is a pointer 
variable, and DADDR is a pointer and DSTR is a based string both with 
DPOINT as their base pointer, the following code would succeed: 

PNTR = CONTS (CELLAD); 

DPOINT = CONTS (PNTR); 

VSTR = SUBSTR(DSTR, STRLNTH(PNTR - > DADDR)); 

On the other hand, this SLIP code would succeed also: 

CALL DATUM(CELLAD, VSTR); 
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Appendix D 

A SNOBOL-Like Function in PL- I 



FIX’ - SNOSC AN (variable number of character string arguments) 

SNOSCAN does not strictly belong in a discussion of SLIP functions, 
but is included here because it was developed in conjunction with the SLIP 
effort and because it represents another facet of the attempt to make PL-I 
an even more general language. 

SNOSCAN is intended to perform the major string manipulating function 
of PNOBOL, and its syntax and abilities are adapted directly from SNOBOL 
to PL-I. Arguments to SNOSCAN are all character strings, and should 
genera] ly be of varying length; they fall into four general categories: 

1. The first argument is the string to be scanned (STR). 

2. The second arguments are pattern strings or variable strings to 
be matched in STR* These arguments are optional and may be omitted. 

3. The third argument is the string (of length 3) It is 

optional also; if it is omitted, arguments of the fourth type are also 
omitted . 

4. The fourth arguments are strings to be substituted in STR for 
the substring of STR successfully matched by the Type 2 arguments. 

Briefly, SNOSCAN allows a string STR to be scanned for particular 
patterns; the part of STR which is matched may be left alone, may be 
deleted, or may be replaced by another set of patterns. SNOSCAN returns 
' l'B if all parts of the scan are successful; it returns 'O'B if any part 
fails, although depending on the part that failed some or all of the 
string arguments may be successfully modified. 
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I. Pattern matching. The first part of SNOSCAN tries to find a 
substring of STR which matches the concatenation of the Type 2 arguments. 

(If there are no Type 2 arguments , the match is deemed successful with the 
matched substring all of STR.) Type 2 arguments may be either patterns 
or variables: 

A. Patterns are nonnull strings of characters to be matched in 
STR. Patterns may have optionally an explicit Position , which says that 
the match can be successful only at a given distance from the start of 
STR. (This corresponds to ANCHOR mode in SNOBOL.) The Position, if 
explicit, is indicated by "xxx" at the start of the pattern; xxx is an 
unsigned string of decimal characters; there may be any number of characters 
in xxx. "1" corresponds to the first character in STR. (The match 
attempted begins with the first character after the Position indicator. 

If the user wishes to match a pattern which begins with the double quote 
", he should repeat it: The first one is ignored in the scan.) 

Sample patterns: 

' ABCDEF' 

' DYNAMITE ' 

'" 53 " DYNAMITE 1 

'""23 SKIDDOO'" 

’""RATS," CRIED CHARLIE BROWN.' 

The second and third patterns are identical except that the third requires 
a match starting at the 53rd character of STR. Note in the fourth and fifth 
patterns that only an initial double quote must be doubled; later ones are 
interpreted properly. 

B. Variables are null strings which will be given nonnull 



length and values if the scan is successful. Variables are useful for three 
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main purposes: assigning a value to a variable, skipping an unimportant 

portion of STR between two substrings which must be matched exactly, and 
looking for repeating patterns in STR via the backreferencing 'feature of 
SNOCCAN. ' 

Variables may have optionally a Position, as for patterns, and a 
Length ; thus a variable may not really be a null string: the important 

point is that it is null after any Position or Length specifications. 
Position is indicated as it was for patterns; Length is shown in the same 
way. Position always precedes Length; if one wants to indicate only 
Length, the Position number may be replaced by a single nonnumeric 
character (not "). 

Sample variables: 

1 1 

» "57" i 
* it ” 13 ” ’ 

t" * 

"'x''' 10352'" 

The second example specifies a position in STR at which it must begin; the 
third example also specifies that the' variable must be exactly 13 characters 
long. The fourth example specifies Length but not Position, as does the 
fifth. The fifth also points out the fact that strings may be up to the 
maximum allowed by PI— I. 

Severa'rvSimple examples will illustrate the kinds of pattern matching 
SNOSCAN can do: 

FLAG = SNOSCAN(STR, A); (A is a pattern.) The string STR is searched 
for a substring (which may be all of STR) equal to A. If A has an explicit 
Position indicator, the match will be attempted only at the proper offset 
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in STR; otherwise the match will be tried at all positions, starting at 
the left end of STR. 

FLAG = SNOSCAN(STR, A, B); (A, B are patterns.) A match for A is 
looked for as described above. If successful, the next substring of STR 
is compared to B. 

FLAG = SNOSCAN(STR, X); (X is a variable.) X is set equal to STR. 

If X has Position or Length restrictions, it is set equal to the specified 
substring. 

FLAG = SN0SCAN(STR, X, X); (X is a variable.) SNOSCAN tries to find 
a repeating substring in STR, starting with the beginning of STR (unless 
X has an explicit Position, in which case X could only end up null), 
subject to any Length indicator in X. If successful, X is set equal to 
that substring; if not, X is made null and SNOSCAN still succeeds. 

FLAG = SN0SCAN(STR, X, A); (A is a pattern; X is a variable.) STR 
is searched for A; if successful, X is made equal to the portion of STR 
from the beginning up to the beginning of A. (SNOSCAN fails if there is 
any contradiction of ejqplicit Length or Position with what is actually 
found . ) 

FLAG = SN0SCAN(STR, A, X); (A is a pattern; X is a variable.) As 
in the previous example, except X is made equal to the substring of STR 
after the end of A. 

FLAG = SN0SCAN(STR, A, X, B); (A, B are patterns; X is a variable.) 
STR is searched for A and the portion of STR after A is searched for B; if 
successful, X is made equal to the substring of STR between A and B. 

FLAG = SN0SCAN(STR, A, X, B, X); (A, B are patterns; X is a variable.) 
STR is searched for A, the portion of STR after A is searched for B, and 
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the portion of STR after B is searched (in ANCHOR mode) for the substring 
of STR between A and B. If all is successful, X is set to the value of 
that intermediate substring. This demonstrates the backreferencing 
feature. There may be any number of references to the same variable in a 
single call, and there may be any number of variables which are back- 
referenced in a single call. 

II. Substitution. In all the examples considered up to now, 3N0SCA11 
has only been asked to see if STR contains a particular pattern- -although 
the specification of that pattern can become quite complex. By using the 
Type 3 argument with or without Type 2 or Type 1 arguments, it is 

possible to change the value of STR. 

Type 2 arguments serve to mark out the portion of STR to be modified. 
If no Type 2 arguments are present, all of STR is to be changed. 

Type 1 arguments give the value of the character segment which v/ill 
be inserted in place of the part of STR to be changed. If no Type 4 
arguments are present, the part of STR to be changed is simply deleted. 

It is possible to reuse some of the Type 2 arguments as Type 4 
arguments in the same call. Variables which had to be matched are given 
their final value at the end of the scanning portion of SNOSCAN, so that 
they may be used to replace part of STR. 

E.g., FLAG = S NOSCAN (STR, A, B, " , ="', B, A); (A, B are patterns.) 
This, if successful, simply interchanges two portions of STR. 

FLAG = SNOSCAN(STR, X, x); (X is a variable.) This sets X 
equal to STR (assuming no explicit Position of Length indicators) and 
replaces STR by itself. 
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SNOSCAN is intended to modify strings; therefore a few words of 
caution are in order. 

1. One is best off using variable length strings if they are going 
to be changed by SNOSCAN* PL-I does not assume it knows the length of 
such strings, as it does with fixed length ones, and looks up the length 
each time. Also, SNOSCAN resets the length of strings it modifies; this 
could be hazardous if the string is really fixed length- -SNOSCAN has no way 
of telling them apart at execution time. 

2. Make sure the strings are of adequate length. With one exception, 
SNOSCAN fails as soon as it tries to substitute a character string that is 
too long for the maximum length of its destination string. The exception 
is in modifying STR itself. If SNOSCAN has succeeded up to the point of 
changing STR (the last thing it does), it will modify STR up to its maximum 
length and throw away the rest of the characters it was supposed to put 

in STR. Instead of returning 'l'B, SNOSCAN will return 'O'B to indicate 
that something went less than perfectly. 



